rigortype 0.1.10 → 0.1.11

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

@@ -0,0 +1,310 @@
+# 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
+          entries = []
+          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|
+              entries << build_class_entry(class_name, path, def_nodes)
+            end
+          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)
+            yield full_name, def_nodes
+          end
+
+          inner_path = lexical_path + [class_local_name]
+          walk_for_mailers(node.body, inner_path, &) if node.body
+        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)
+          actions = def_nodes.to_h do |def_node|
+            entry = build_action_entry(def_node)
+            [entry.method_name, entry]
+          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
+          )
+        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,76 @@
+# 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) do
+          def find_action(method_name)
+            actions[method_name.to_sym]
+          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

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "actionmailer/mailer_index"
+require_relative "actionmailer/mailer_discoverer"
+require_relative "actionmailer/analyzer"
+
+module Rigor
+  module Plugin
+    # 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
+    # Prism — no `action_mailer` runtime dependency.
+    #
+    # ## Configuration
+    #
+    #     plugins:
+    #       - gem: rigor-actionmailer
+    #         config:
+    #           mailer_search_paths: ["app/mailers"]                  # default; optional
+    #           mailer_base_classes: ["ApplicationMailer", "ActionMailer::Base"]  # default; optional
+    #           views_root: "app/views"                                # default; optional
+    #
+    # ## What it checks
+    #
+    # 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`.
+    #
+    # ## 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.
+    class Actionmailer < Rigor::Plugin::Base
+      manifest(
+        id: "actionmailer",
+        version: "0.1.0",
+        description: "Validates ActionMailer call shape and view template existence.",
+        config_schema: {
+          "mailer_search_paths" => :array,
+          "mailer_base_classes" => :array,
+          "views_root" => :string
+        }
+      )
+
+      DEFAULT_MAILER_SEARCH_PATHS = ["app/mailers"].freeze
+      DEFAULT_MAILER_BASE_CLASSES = %w[ApplicationMailer ActionMailer::Base].freeze
+      DEFAULT_VIEWS_ROOT = "app/views"
+
+      producer :mailer_index do |_params|
+        MailerDiscoverer.new(
+          io_boundary: io_boundary,
+          search_paths: @mailer_search_paths,
+          base_classes: @mailer_base_classes,
+          views_root: @views_root
+        ).discover
+      end
+
+      def init(_services)
+        @mailer_search_paths = Array(config.fetch("mailer_search_paths", DEFAULT_MAILER_SEARCH_PATHS)).map(&:to_s)
+        @mailer_base_classes = Array(config.fetch("mailer_base_classes", DEFAULT_MAILER_BASE_CLASSES)).map(&:to_s)
+        @views_root = config.fetch("views_root", DEFAULT_VIEWS_ROOT).to_s
+        @mailer_index = nil
+        @load_error = nil
+      end
+
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        index = mailer_index_or_nil
+        return [load_error_diagnostic(path)] if index.nil? && @load_error
+        return [] if index.nil? || index.empty?
+
+        diagnostics = []
+        diagnostics.concat(call_site_diagnostics(path, root, index))
+        diagnostics.concat(missing_view_diagnostics(path, index))
+        diagnostics
+      end
+
+      private
+
+      def mailer_index_or_nil
+        return @mailer_index if @mailer_index
+
+        # Two-glob descriptor: every mailer class under
+        # `mailer_search_paths` AND every view template under
+        # `views_root`. Without explicit enumeration the cache
+        # invalidates only on files the `IoBoundary` has already
+        # read in the current process — empty on the first call
+        # of a fresh process, so warm hits would serve stale
+        # `MailerIndex` data after mailers are added / removed or
+        # view templates are added (`view_exists?` failures aren't
+        # recorded, so the auto-built descriptor cannot detect a
+        # newly-added view).
+        mailer_d = glob_descriptor(@mailer_search_paths, "**/*.rb")
+        view_d = glob_descriptor([@views_root], "**/*")
+        descriptor = Rigor::Cache::Descriptor.compose(mailer_d, view_d)
+        @mailer_index = cache_for(:mailer_index, params: {}, descriptor: descriptor).call
+      rescue StandardError => e
+        @load_error = "rigor-actionmailer: failed to discover mailers: #{e.class}: #{e.message}"
+        nil
+      end
+
+      def call_site_diagnostics(path, root, index)
+        Analyzer.diagnose(path: path, root: root, mailer_index: index).map { |diag| build_diagnostic(diag) }
+      end
+
+      # 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)
+        return [] if class_entry.nil? || class_entry.missing_views.empty?
+
+        class_entry.missing_views.map do |action_name|
+          action_entry = class_entry.find_action(action_name)
+          Rigor::Analysis::Diagnostic.new(
+            path: path,
+            line: action_entry&.def_line || 1,
+            column: action_entry&.def_column || 1,
+            severity: :warning,
+            rule: "missing-view",
+            message: "`#{class_entry.class_name}##{action_name}` has no view template " \
+                     "under `#{@views_root}/#{underscore(class_entry.class_name.delete_prefix('::'))}/`"
+          )
+        end
+      end
+
+      def canonical_path(path)
+        File.realpath(path)
+      rescue StandardError
+        File.expand_path(path)
+      end
+
+      def underscore(name)
+        name.gsub("::", "/")
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+      end
+
+      def load_error_diagnostic(path)
+        Rigor::Analysis::Diagnostic.new(
+          path: path, line: 1, column: 1,
+          message: @load_error,
+          severity: :warning,
+          rule: "load-error"
+        )
+      end
+
+      def build_diagnostic(diag)
+        Rigor::Analysis::Diagnostic.new(
+          path: diag.path, line: diag.line, column: diag.column,
+          message: diag.message, severity: diag.severity, rule: diag.rule
+        )
+      end
+    end
+
+    Rigor::Plugin.register(Actionmailer)
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/actionmailer"