rigortype 0.1.10 → 0.1.12

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+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}.
+      #
+      # 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.
+        ENTRY_METHODS = %i[perform_later perform_now perform].freeze
+
+        Diagnostic = Struct.new(:path, :line, :column, :severity, :rule, :message, keyword_init: true)
+
+        module_function
+
+        # @param path [String]
+        # @param root [Prism::Node]
+        # @param job_index [JobIndex]
+        # @return [Array<Diagnostic>]
+        def diagnose(path:, root:, job_index:)
+          diagnostics = []
+          walk(root) do |call_node|
+            class_name = constant_receiver_name(call_node.receiver)
+            next if class_name.nil?
+
+            entry = job_index.find(class_name) || job_index.find("::#{class_name}")
+            next if entry.nil?
+
+            diagnostics << info_diagnostic(path, call_node, entry)
+            arity = arity_check(path, call_node, entry)
+            diagnostics << arity if arity
+          end
+          diagnostics
+        end
+
+        def walk(node, &)
+          return unless node.is_a?(Prism::Node)
+
+          yield node if node.is_a?(Prism::CallNode) && entry_call?(node)
+          node.compact_child_nodes.each { |child| walk(child, &) }
+        end
+
+        def entry_call?(node)
+          ENTRY_METHODS.include?(node.name) &&
+            (node.receiver.is_a?(Prism::ConstantReadNode) || node.receiver.is_a?(Prism::ConstantPathNode))
+        end
+
+        def info_diagnostic(path, call_node, entry)
+          location = call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :info,
+            rule: "job-call",
+            message: "`#{entry.class_name}.#{call_node.name}` matches `#perform` (arity #{entry.arity_label})"
+          )
+        end
+
+        def arity_check(path, call_node, entry)
+          actual = (call_node.arguments&.arguments || []).size
+          return nil if entry.accepts?(actual)
+
+          location = call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :error,
+            rule: "wrong-arity",
+            message: "`#{entry.class_name}.#{call_node.name}` expects #{entry.arity_label} argument(s), got #{actual}"
+          )
+        end
+
+        # 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
+          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-activejob/lib/rigor/plugin/activejob/job_discoverer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "prism"
+
+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.
+      #
+      # 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
+      #   `module Admin`).
+      # - 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
+          @search_paths = search_paths
+          @base_classes = base_classes.to_set
+        end
+
+        # @return [JobIndex]
+        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_jobs(tree, []) do |class_name, perform_def|
+              entries << build_entry(class_name, perform_def)
+            end
+          end
+          JobIndex.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_jobs(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_jobs(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)
+            perform_def = lookup_perform_def(node.body)
+            yield full_name, perform_def
+          end
+
+          inner_path = lexical_path + [class_local_name]
+          walk_for_jobs(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_jobs(node.body, inner_path, &) if node.body
+        end
+
+        # Renders `Foo::Bar` / `::Foo::Bar` as a String.
+        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 `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?
+
+          body.compact_child_nodes.each do |node|
+            next unless node.is_a?(Prism::DefNode) && node.name == :perform
+            next if node.receiver.is_a?(Prism::SelfNode)
+
+            return node
+          end
+          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.
+        def build_entry(class_name, perform_def)
+          if perform_def.nil?
+            return JobIndex::Entry.new(
+              class_name: class_name, min_arity: 0,
+              max_arity: Float::INFINITY, keyword_required: []
+            )
+          end
+
+          parameters = perform_def.parameters
+          if parameters.nil?
+            return JobIndex::Entry.new(
+              class_name: class_name, min_arity: 0,
+              max_arity: 0, keyword_required: []
+            )
+          end
+
+          required_count = (parameters.requireds || []).size
+          optional_count = (parameters.optionals || []).size
+          rest_present = !parameters.rest.nil?
+          keyword_required = (parameters.keywords || []).filter_map do |kw|
+            kw.name if kw.is_a?(Prism::RequiredKeywordParameterNode)
+          end
+
+          JobIndex::Entry.new(
+            class_name: class_name,
+            min_arity: required_count,
+            max_arity: rest_present ? Float::INFINITY : required_count + optional_count,
+            keyword_required: keyword_required.map(&:to_sym)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # `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 only
+      # validates positional arity for v0.1.0.
+      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+`.
+          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
+
+          # Predicate for the analyzer's wrong-arity check.
+          def accepts?(actual)
+            actual.between?(min_arity, max_arity)
+          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 [Entry, nil]
+        def find(class_name)
+          @by_name[class_name.to_s]
+        end
+
+        def known?(class_name)
+          @by_name.key?(class_name.to_s)
+        end
+
+        def empty?
+          @entries.empty?
+        end
+
+        def size
+          @entries.size
+        end
+
+        def names
+          @by_name.keys
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "activejob/job_index"
+require_relative "activejob/job_discoverer"
+require_relative "activejob/analyzer"
+
+module Rigor
+  module Plugin
+    # 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.
+    #
+    # ## Configuration
+    #
+    #     plugins:
+    #       - gem: rigor-activejob
+    #         config:
+    #           job_search_paths: ["app/jobs"]                  # default; optional
+    #           job_base_classes: ["ApplicationJob", "ActiveJob::Base"]  # default; optional
+    #
+    # ## 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).
+    class Activejob < Rigor::Plugin::Base
+      manifest(
+        id: "activejob",
+        version: "0.1.0",
+        description: "Validates ActiveJob `Job.perform_later` argument arity.",
+        config_schema: {
+          "job_search_paths" => :array,
+          "job_base_classes" => :array
+        }
+      )
+
+      DEFAULT_JOB_SEARCH_PATHS = ["app/jobs"].freeze
+      DEFAULT_JOB_BASE_CLASSES = %w[ApplicationJob ActiveJob::Base].freeze
+
+      # Cached: discovered job index. The producer reads every
+      # file under `job_search_paths` via the trusted
+      # `IoBoundary`; the descriptor's auto-collected
+      # `FileEntry` digests invalidate the cache when any of
+      # those files change.
+      producer :job_index do |_params|
+        JobDiscoverer.new(
+          io_boundary: io_boundary,
+          search_paths: @job_search_paths,
+          base_classes: @job_base_classes
+        ).discover
+      end
+
+      def init(_services)
+        @job_search_paths = Array(config.fetch("job_search_paths", DEFAULT_JOB_SEARCH_PATHS)).map(&:to_s)
+        @job_base_classes = Array(config.fetch("job_base_classes", DEFAULT_JOB_BASE_CLASSES)).map(&:to_s)
+        @job_index = nil
+        @load_error = nil
+      end
+
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        index = job_index_or_nil
+        return [load_error_diagnostic(path)] if index.nil? && @load_error
+        return [] if index.nil? || index.empty?
+
+        Analyzer.diagnose(path: path, root: root, job_index: index).map { |diag| build_diagnostic(diag) }
+      end
+
+      private
+
+      def job_index_or_nil
+        return @job_index if @job_index
+
+        # Read-then-cache pattern: the discoverer's
+        # IoBoundary reads happen INSIDE `discover`, which is
+        # invoked through `cache_for`'s producer block. The
+        # boundary's accumulated FileEntry digests get
+        # captured into the descriptor at cache_for time.
+        @job_index = cache_for(:job_index, params: {}).call
+      rescue StandardError => e
+        @load_error = "rigor-activejob: failed to discover jobs: #{e.class}: #{e.message}"
+        nil
+      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(Activejob)
+  end
+end

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

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