rigortype 0.1.10 → 0.1.12

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class Actionmailer < Rigor::Plugin::Base
+      # Walks a parsed file's AST looking for
+      # `<MailerClass>.<action>(...)` calls and validates
+      # each against the {MailerIndex}. Recognises both:
+      #
+      # - `UserMailer.welcome(user)` — direct action call
+      #   (the call returns a `Mail::Message` ready for
+      #   `.deliver_now` / `.deliver_later`).
+      # - `UserMailer.with(user: u).welcome` — parametrized
+      #   action call. The `.with(...)` call is treated as a
+      #   pass-through; the action's argument shape is
+      #   validated on the trailing `.welcome` invocation
+      #   even though the receiver is a method-call chain
+      #   rather than a constant.
+      #
+      # The analyzer is purely syntactic: it does not look
+      # at runtime mailer state. Constants that don't appear
+      # in the index are silently ignored — the rule has no
+      # opinion on non-mailer call shapes.
+      module Analyzer
+        # `.with(...)` is recognised as a forwarding step:
+        # the receiver of `.with(...)` is the mailer class,
+        # so the trailing action-method call's class context
+        # is the same.
+        WITH_METHODS = %i[with].freeze
+
+        # Ruby method names that ActionMailer reserves on the
+        # class itself. We don't validate against these as
+        # actions even if a mailer happens to override them
+        # — the user almost certainly meant the framework
+        # method, not their own action.
+        RESERVED_CLASS_METHODS = %i[
+          new allocate name superclass class
+          deliver_later deliver_now deliver_later! deliver_now!
+          mail headers attachments default
+          with parameters
+          respond_to? respond_to_missing? method_defined?
+          public_send send __send__ public_method
+          method instance_method methods
+        ].freeze
+
+        Diagnostic = Struct.new(:path, :line, :column, :severity, :rule, :message, keyword_init: true)
+
+        module_function
+
+        # @param path [String]
+        # @param root [Prism::Node]
+        # @param mailer_index [MailerIndex]
+        # @return [Array<Diagnostic>]
+        def diagnose(path:, root:, mailer_index:)
+          diagnostics = []
+          walk(root) do |call_node|
+            class_name = mailer_class_for_call(call_node)
+            next if class_name.nil?
+            next if RESERVED_CLASS_METHODS.include?(call_node.name)
+
+            class_entry = mailer_index.find(class_name) || mailer_index.find("::#{class_name}")
+            next if class_entry.nil?
+
+            action_entry = class_entry.find_action(call_node.name)
+            if action_entry.nil?
+              # Skip `unknown-action` when the mailer's include
+              # set has any unresolved module — the unresolved
+              # module may legitimately define the action
+              # (gem-shipped concern, dynamically loaded
+              # mailer extension). Mirrors the same predicate
+              # `rigor-actionpack` uses for unknown-filter-method.
+              next if class_entry.unresolved_includes?
+
+              diagnostics << unknown_action_diagnostic(path, call_node, class_entry)
+              next
+            end
+
+            diagnostics << action_call_info(path, call_node, class_entry, action_entry)
+            arity_diag = arity_check(path, call_node, class_entry, action_entry)
+            diagnostics << arity_diag if arity_diag
+          end
+          diagnostics
+        end
+
+        # Walks the tree yielding every CallNode whose receiver
+        # resolves (directly or through `.with(...)`) to a
+        # constant.
+        def walk(node, &)
+          return unless node.is_a?(Prism::Node)
+
+          yield node if node.is_a?(Prism::CallNode) && action_call_candidate?(node)
+          node.compact_child_nodes.each { |child| walk(child, &) }
+        end
+
+        def action_call_candidate?(node)
+          # Skip anything that doesn't look like a mailer
+          # action call: no receiver, or a non-constant /
+          # non-`.with(...)` receiver.
+          return false if node.receiver.nil?
+
+          mailer_class_for_call(node) ? true : false
+        end
+
+        # Extracts the mailer class name when the call's
+        # receiver is either:
+        # - A constant (`UserMailer.welcome(...)`), or
+        # - A `.with(...)` call whose receiver is a constant
+        #   (`UserMailer.with(user: u).welcome`).
+        def mailer_class_for_call(node)
+          receiver = node.receiver
+          case receiver
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            constant_receiver_name(receiver)
+          when Prism::CallNode
+            return nil unless WITH_METHODS.include?(receiver.name)
+
+            constant_receiver_name(receiver.receiver)
+          end
+        end
+
+        def action_call_info(path, call_node, class_entry, action_entry)
+          location = call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :info,
+            rule: "mailer-call",
+            message: "`#{class_entry.class_name}.#{action_entry.method_name}` " \
+                     "matches mailer action (arity #{action_entry.arity_label})"
+          )
+        end
+
+        def arity_check(path, call_node, class_entry, action_entry)
+          args = call_node.arguments&.arguments || []
+          actual = args.size
+          return nil if action_entry.accepts?(actual)
+
+          # Trailing keyword-hash relaxation. `Notify.foo(uid,
+          # gid, success_count: 5)` is 3 positional args from
+          # Prism's perspective (2 + a KeywordHashNode); the
+          # action's `def foo(uid, gid, success_count:)` has
+          # arity 2. When the call's trailing arg is a kwargs
+          # hash, allow `(actual - 1) ≤ max_arity` so kwargs-
+          # carrying calls don't surface as wrong-arity.
+          return nil if args.last.is_a?(Prism::KeywordHashNode) && action_entry.accepts?(actual - 1)
+
+          location = call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :error,
+            rule: "wrong-arity",
+            message: "`#{class_entry.class_name}.#{action_entry.method_name}` " \
+                     "expects #{action_entry.arity_label} argument(s), got #{actual}"
+          )
+        end
+
+        def unknown_action_diagnostic(path, call_node, class_entry)
+          location = call_node.location
+          known = class_entry.actions.keys.sort.join(", ")
+          known_part = known.empty? ? "no actions defined" : "known actions: #{known}"
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :error,
+            rule: "unknown-action",
+            message: "`#{class_entry.class_name}.#{call_node.name}` is not a defined " \
+                     "mailer action (#{known_part})"
+          )
+        end
+
+        def constant_receiver_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then constant_path_name(node)
+          end
+        end
+
+        def constant_path_name(node)
+          parts = []
+          current = node
+          while current.is_a?(Prism::ConstantPathNode)
+            parts.unshift(current.name.to_s)
+            current = current.parent
+          end
+          case current
+          when nil then "::#{parts.join('::')}"
+          when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+require "prism"
+
+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.
+      #
+      # 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.
+      #
+      # 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.
+      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
+        #   `app/views`).
+        def initialize(io_boundary:, search_paths:, base_classes:, views_root: DEFAULT_VIEWS_ROOT)
+          @io_boundary = io_boundary
+          @search_paths = search_paths
+          @base_classes = base_classes.to_set
+          @views_root = views_root
+        end
+
+        # @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/`.
+          module_actions = {} # module_fqn => Hash<Symbol, ActionEntry>
+          class_visits = []   # collected (class_name, path, def_nodes, includes)
+
+          ruby_files_under(@search_paths).each do |path|
+            contents = read_safely(path)
+            next if contents.nil?
+
+            tree = Prism.parse(contents).value
+            walk_for_mailers(tree, []) do |class_name, def_nodes, includes|
+              class_visits << [class_name, path, def_nodes, includes]
+            end
+            collect_module_actions(tree, [], module_actions)
+          end
+
+          entries = class_visits.map do |class_name, path, def_nodes, includes|
+            build_class_entry(class_name, path, def_nodes, includes, module_actions)
+          end
+          MailerIndex.new(entries)
+        end
+
+        private
+
+        def read_safely(path)
+          @io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          nil
+        end
+
+        def ruby_files_under(roots)
+          roots.flat_map do |root|
+            absolute = File.expand_path(root)
+            next [] unless File.directory?(absolute)
+
+            Dir.glob(File.join(absolute, "**", "*.rb"))
+          end
+        end
+
+        def walk_for_mailers(node, lexical_path, &)
+          return if node.nil?
+
+          case node
+          when Prism::ClassNode then visit_class(node, lexical_path, &)
+          when Prism::ModuleNode then visit_module(node, lexical_path, &)
+          else
+            node.compact_child_nodes.each { |child| walk_for_mailers(child, lexical_path, &) }
+          end
+        end
+
+        def visit_class(node, lexical_path, &)
+          class_local_name = constant_path_name(node.constant_path)
+          return if class_local_name.nil?
+
+          full_name = (lexical_path + [class_local_name]).join("::")
+          superclass = constant_path_name(node.superclass) if node.superclass
+          if superclass && @base_classes.include?(superclass)
+            def_nodes = collect_action_defs(node.body)
+            includes = collect_includes(node.body)
+            yield full_name, def_nodes, includes
+          end
+
+          inner_path = lexical_path + [class_local_name]
+          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
+        # `Emails::Issues`, `Emails::MergeRequests`, etc.).
+        def collect_includes(body)
+          return [] if body.nil?
+
+          names = []
+          body.compact_child_nodes.each do |node|
+            next unless node.is_a?(Prism::CallNode) && node.receiver.nil? && node.name == :include
+
+            (node.arguments&.arguments || []).each do |arg|
+              name = constant_path_name(arg)
+              names << name.delete_prefix("::") if name
+            end
+          end
+          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).
+        def collect_module_actions(node, lexical_path, accumulator)
+          return if node.nil?
+
+          case node
+          when Prism::ModuleNode
+            local_name = constant_path_name(node.constant_path)
+            return if local_name.nil?
+
+            full_name = (lexical_path + [local_name.delete_prefix("::")]).join("::")
+            if node.body
+              def_nodes = collect_action_defs(node.body)
+              entries = def_nodes.to_h { |def_node| [def_node.name, build_action_entry(def_node)] }
+              accumulator[full_name] = entries unless entries.empty?
+              collect_module_actions(node.body, lexical_path + [local_name.delete_prefix("::")], accumulator)
+            end
+          when Prism::ClassNode
+            local_name = constant_path_name(node.constant_path)
+            inner = local_name ? lexical_path + [local_name.delete_prefix("::")] : lexical_path
+            collect_module_actions(node.body, inner, accumulator) if node.body
+          else
+            node.compact_child_nodes.each { |child| collect_module_actions(child, lexical_path, accumulator) }
+          end
+        end
+
+        def visit_module(node, lexical_path, &)
+          module_local_name = constant_path_name(node.constant_path)
+          return if module_local_name.nil?
+
+          inner_path = lexical_path + [module_local_name]
+          walk_for_mailers(node.body, inner_path, &) if node.body
+        end
+
+        def constant_path_name(node)
+          return nil if node.nil?
+
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parts = []
+            current = node
+            while current.is_a?(Prism::ConstantPathNode)
+              parts.unshift(current.name.to_s)
+              current = current.parent
+            end
+            case current
+            when nil then "::#{parts.join('::')}"
+            when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+            end
+          end
+        end
+
+        # Returns the instance-side `def` nodes that look like
+        # mailer actions. Filters non-actions:
+        # - `initialize`
+        # - 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 named as a `private :foo` argument
+        # - 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.
+        CALLBACK_DECLARATIONS = %i[before_action after_action around_action].freeze
+        private_constant :CALLBACK_DECLARATIONS
+
+        def collect_action_defs(body)
+          return [] if body.nil?
+
+          private_names, callback_names = collect_visibility_and_callbacks(body)
+          visibility = :public
+
+          body.compact_child_nodes.flat_map do |node|
+            visibility = next_visibility(node, visibility)
+            next [] unless node.is_a?(Prism::DefNode)
+            next [] if node.receiver.is_a?(Prism::SelfNode)
+            next [] if node.name == :initialize
+            next [] if node.name.to_s.start_with?("_")
+            next [] if visibility == :private
+            next [] if private_names.include?(node.name)
+            next [] if callback_names.include?(node.name)
+
+            [node]
+          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.).
+        def collect_visibility_and_callbacks(body)
+          private_names = []
+          callback_names = []
+
+          body.compact_child_nodes.each do |node|
+            next unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+
+            args = (node.arguments&.arguments || []).filter_map do |arg|
+              arg.is_a?(Prism::SymbolNode) ? arg.unescaped.to_sym : nil
+            end
+            next if args.empty?
+
+            case node.name
+            when :private, :protected then private_names.concat(args)
+            when *CALLBACK_DECLARATIONS then callback_names.concat(args)
+            end
+          end
+
+          [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`).
+        def next_visibility(node, current)
+          return current unless node.is_a?(Prism::CallNode)
+          return current unless node.receiver.nil?
+          return current unless (args = node.arguments&.arguments).nil? || args.empty?
+
+          case node.name
+          when :private then :private
+          when :protected then :protected
+          when :public then :public
+          else current
+          end
+        end
+
+        def build_class_entry(class_name, file_path, def_nodes, includes = [], module_actions = {})
+          actions = def_nodes.to_h do |def_node|
+            entry = build_action_entry(def_node)
+            [entry.method_name, entry]
+          end
+
+          # Merge in actions from include'd modules. The
+          # discoverer pre-collected every module's defs as
+          # `module_actions` keyed by fully-qualified module
+          # name. We resolve each include against that map —
+          # tries the full include name first, then walks down
+          # the class's lexical chain looking for a nested
+          # match (e.g. `Emails::Issues` inside `class Notify`
+          # at top-level resolves to top-level `Emails::Issues`).
+          # Includes we cannot resolve are silently skipped;
+          # the per-mailer `unresolved_includes?` predicate
+          # below (consumed by the analyzer) downgrades
+          # `unknown-action` to silence when any include is
+          # unresolved.
+          unresolved_includes = []
+          includes.each do |include_name|
+            inc_actions = module_actions[include_name]
+            if inc_actions.nil?
+              unresolved_includes << include_name
+              next
+            end
+
+            inc_actions.each do |method_name, entry|
+              actions[method_name] ||= entry
+            end
+          end
+
+          missing_views = actions.keys.reject { |action| view_exists?(class_name, action) }
+
+          MailerIndex::ClassEntry.new(
+            class_name: class_name,
+            file_path: file_path,
+            actions: actions,
+            missing_views: missing_views,
+            unresolved_includes: unresolved_includes.freeze
+          )
+        end
+
+        def build_action_entry(def_node)
+          parameters = def_node.parameters
+          location = def_node.name_loc
+
+          if parameters.nil?
+            return MailerIndex::ActionEntry.new(
+              method_name: def_node.name,
+              min_arity: 0, max_arity: 0,
+              def_line: location.start_line,
+              def_column: location.start_column + 1
+            )
+          end
+
+          required_count = (parameters.requireds || []).size
+          optional_count = (parameters.optionals || []).size
+          rest_present = !parameters.rest.nil?
+
+          MailerIndex::ActionEntry.new(
+            method_name: def_node.name,
+            min_arity: required_count,
+            max_arity: rest_present ? Float::INFINITY : required_count + optional_count,
+            def_line: location.start_line,
+            def_column: location.start_column + 1
+          )
+        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.
+        def view_exists?(class_name, action_name)
+          views_root_absolute = File.expand_path(@views_root)
+          underscore_path = underscore(class_name.delete_prefix("::"))
+          mailer_dir = File.join(views_root_absolute, underscore_path)
+
+          VIEW_FORMATS.any? do |format|
+            VIEW_EXTENSIONS.any? do |ext|
+              candidate = File.join(mailer_dir, "#{action_name}.#{format}.#{ext}")
+              read_safely(candidate)
+            end
+          end
+        end
+
+        # Convert `Foo::BarMailer` → `foo/bar_mailer`. Mirrors
+        # ActiveSupport's String#underscore for ASCII-only
+        # constant names; we don't try to be inflector-perfect
+        # here.
+        def underscore(name)
+          name.gsub("::", "/")
+              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    class Actionmailer < Rigor::Plugin::Base
+      # Frozen catalogue of discovered Mailer classes, each
+      # carrying:
+      #
+      # - 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/`
+      class MailerIndex
+        ActionEntry = Data.define(:method_name, :min_arity, :max_arity, :def_line, :def_column) do
+          def arity_label
+            return "#{min_arity}+" if max_arity == Float::INFINITY
+            return min_arity.to_s if min_arity == max_arity
+
+            "#{min_arity}..#{max_arity}"
+          end
+
+          def accepts?(actual)
+            actual.between?(min_arity, max_arity)
+          end
+        end
+
+        ClassEntry = Data.define(:class_name, :file_path, :actions, :missing_views, :unresolved_includes) do
+          def find_action(method_name)
+            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.
+          def unresolved_includes?
+            !unresolved_includes.empty?
+          end
+        end
+
+        attr_reader :entries
+
+        def initialize(entries)
+          @entries = entries.freeze
+          @by_name = entries.to_h { |entry| [entry.class_name, entry] }.freeze
+          freeze
+        end
+
+        # @return [ClassEntry, nil]
+        def find(class_name)
+          @by_name[class_name.to_s]
+        end
+
+        def known?(class_name)
+          @by_name.key?(class_name.to_s)
+        end
+
+        # @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)
+          @entries.find { |entry| entry.file_path == file_path }
+        end
+
+        def empty?
+          @entries.empty?
+        end
+
+        def size
+          @entries.size
+        end
+
+        def names
+          @by_name.keys
+        end
+      end
+    end
+  end
+end