rigortype 0.1.10 → 0.1.11

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"

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

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class Activerecord < Rigor::Plugin::Base
+      # Per-file AST walker. For each `Model.find(...)` /
+      # `Model.find_by(...)` / `Model.where(...)` call where
+      # `Model` is a name in the {ModelIndex}, emits diagnostics:
+      #
+      # | Method | Recognised arg shape | Validation |
+      # | --- | --- | --- |
+      # | `Model.find(id)` | any positional | arity check (1+ args) |
+      # | `Model.find_by(col: v, ...)` | keyword args | each key must be a column |
+      # | `Model.where(col: v, ...)` | keyword args | each key must be a column |
+      # | `Model.where(string)` | String literal | parser-side; not validated |
+      #
+      # Successful matches surface as `:info` diagnostics naming
+      # the resolved table; unknown columns surface as `:error`.
+      # Calls whose receiver is not a model in the index, and
+      # calls with non-keyword arguments to `where` / `find_by`,
+      # stay silent.
+      class Analyzer
+        # Methods that take a column → value Hash and need each key
+        # validated against the receiver's column set. The bang
+        # variants (`find_by!` raises instead of returning nil;
+        # `find_or_create_by!` raises on a validation failure) and
+        # `create_or_find_by` / `create_or_find_by!` take the
+        # identical column-hash argument shape.
+        COLUMN_HASH_METHODS = %i[
+          where
+          find_by find_by!
+          find_or_create_by find_or_create_by!
+          find_or_initialize_by
+          create_or_find_by create_or_find_by!
+        ].freeze
+
+        DID_YOU_MEAN_DISTANCE = 3
+
+        attr_reader :diagnostics
+
+        def initialize(path:, model_index:)
+          @path = path
+          @model_index = model_index
+          @diagnostics = []
+        end
+
+        def analyze(root)
+          walk(root) { |node| visit_call(node) if node.is_a?(Prism::CallNode) }
+          self
+        end
+
+        private
+
+        def walk(node, &)
+          return if node.nil?
+
+          yield node
+          node.compact_child_nodes.each { |child| walk(child, &) }
+        end
+
+        def visit_call(node)
+          model_name = constant_receiver_name(node.receiver)
+          return if model_name.nil?
+
+          entry = @model_index.find(model_name) ||
+                  @model_index.find("::#{model_name}")
+          return if entry.nil?
+
+          case node.name
+          when :find then validate_find(node, entry)
+          when *COLUMN_HASH_METHODS then validate_column_hash_call(node, entry)
+          end
+        end
+
+        def validate_find(node, entry)
+          arity = call_argument_count(node)
+          if arity.zero?
+            push_error(node, "wrong-arity",
+                       "`#{entry.class_name}.find` expects at least 1 argument, got 0")
+            return
+          end
+
+          push_info(node, "model-call",
+                    "`#{entry.class_name}.find` returns #{entry.class_name} (table: `#{entry.table_name}`)")
+        end
+
+        def validate_column_hash_call(node, entry)
+          keyword_pairs = keyword_argument_pairs(node)
+          return push_recognised(node, entry) if keyword_pairs.empty?
+
+          unknown = keyword_pairs.reject { |pair| valid_query_key?(entry, pair[:key]) }
+          if unknown.empty?
+            keyword_pairs.each { |pair| validate_enum_value(node, entry, pair) }
+            push_recognised(node, entry, keyword_pairs.map { |p| p[:key] })
+          else
+            unknown.each do |pair|
+              key = pair[:key]
+              suggestion = closest_column(key, entry.column_names)
+              hint = suggestion ? " (did you mean `:#{suggestion}`?)" : ""
+              push_error(node, "unknown-column",
+                         "`#{entry.class_name}.#{node.name}(#{key}: ...)` references " \
+                         "unknown column `#{key}` on table `#{entry.table_name}`#{hint}")
+            end
+          end
+        end
+
+        # ActiveRecord's `where` / `find_by` / `find_or_initialize_by`
+        # accept either a column name *or* a singular association
+        # name (belongs_to / has_one). The latter resolves to the
+        # association's FK column behind the scenes:
+        #
+        #   AccountPin.find_by(account: x)
+        #   # → SELECT … WHERE account_id = x.id
+        #
+        # Without this allowance, every `find_by(<assoc>:)` call
+        # surfaces as an `unknown-column` false positive — Mastodon
+        # saw ~100 such hits across the API controllers, all of
+        # which were the canonical Rails idiom rather than typos.
+        #
+        # `alias_attribute` names resolve to their target before
+        # the column / association check — querying by an aliased
+        # attribute is a valid Rails idiom and must not surface as
+        # an `unknown-column`.
+        def valid_query_key?(entry, key)
+          key = entry.resolve_alias(key) if entry.alias?(key)
+
+          return true if entry.column?(key)
+
+          assoc = entry.association(key)
+          assoc && assoc[:kind] == :singular
+        end
+
+        # When the column is an enum-bearing column AND the
+        # passed value is a Symbol literal, the value MUST be
+        # one of the declared enum values. Non-Symbol values
+        # (variables, expressions) decline so dynamic call
+        # sites stay silent. Sequences (`status: [:active,
+        # :archived]`) are intentionally NOT walked here —
+        # the relation-shape check belongs in a future track.
+        def validate_enum_value(node, entry, pair)
+          return unless entry.enum?(pair[:key])
+          return unless pair[:value].is_a?(Prism::SymbolNode)
+
+          value = pair[:value].unescaped
+          values = entry.enum_values(pair[:key])
+          return if values.include?(value)
+
+          suggestion = closest_column(value, values)
+          hint = suggestion ? " (did you mean `:#{suggestion}`?)" : ""
+          push_error(node, "unknown-enum-value",
+                     "`#{entry.class_name}.#{node.name}(#{pair[:key]}: :#{value})` references " \
+                     "unknown enum value `:#{value}` (declared: #{values.map { |v| ":#{v}" }.join(', ')})#{hint}")
+        end
+
+        def push_recognised(node, entry, keys = nil)
+          msg = "`#{entry.class_name}.#{node.name}`"
+          msg += " (#{keys.map { |k| ":#{k}" }.join(', ')})" if keys && !keys.empty?
+          msg += " on table `#{entry.table_name}`"
+          push_info(node, "model-call", msg)
+        end
+
+        def constant_receiver_name(node)
+          case node
+          when Prism::ConstantReadNode
+            node.name.to_s
+          when Prism::ConstantPathNode
+            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
+            "::#{parts.join('::')}"
+          when Prism::ConstantReadNode
+            "#{current.name}::#{parts.join('::')}"
+          end
+        end
+
+        def call_argument_count(node)
+          return 0 if node.arguments.nil?
+
+          node.arguments.arguments.size
+        end
+
+        # Returns the symbol-keyed pairs of any KeywordHashNode
+        # argument as `{ key:, value: }` rows. Plain hash-literal
+        # arguments (`Model.where({a: 1})`) are NOT walked —
+        # Rails accepts both, but the keyword form is the
+        # idiomatic one. The `value` Prism node is preserved so
+        # the enum check downstream can recognise Symbol
+        # literals without re-walking the call.
+        def keyword_argument_pairs(node)
+          return [] if node.arguments.nil?
+
+          pairs = []
+          node.arguments.arguments.each do |arg|
+            next unless arg.is_a?(Prism::KeywordHashNode)
+
+            arg.elements.each do |pair|
+              next unless pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode)
+
+              pairs << { key: pair.key.unescaped, value: pair.value }
+            end
+          end
+          pairs
+        end
+
+        def closest_column(name, candidates)
+          best = nil
+          best_distance = DID_YOU_MEAN_DISTANCE + 1
+          candidates.each do |candidate|
+            distance = levenshtein(name, candidate)
+            if distance < best_distance
+              best = candidate
+              best_distance = distance
+            end
+          end
+          best
+        end
+
+        def levenshtein(a, b) # rubocop:disable Naming/MethodParameterName
+          return b.length if a.empty?
+          return a.length if b.empty?
+
+          rows = Array.new(a.length + 1) { |_i| Array.new(b.length + 1, 0) }
+          (0..a.length).each { |i| rows[i][0] = i }
+          (0..b.length).each { |j| rows[0][j] = j }
+
+          (1..a.length).each do |i|
+            (1..b.length).each do |j|
+              cost = a[i - 1] == b[j - 1] ? 0 : 1
+              rows[i][j] = [
+                rows[i - 1][j] + 1,
+                rows[i][j - 1] + 1,
+                rows[i - 1][j - 1] + cost
+              ].min
+            end
+          end
+          rows[a.length][b.length]
+        end
+
+        def push_info(node, rule, message)
+          push_diagnostic(node, severity: :info, rule: rule, message: message)
+        end
+
+        def push_error(node, rule, message)
+          push_diagnostic(node, severity: :error, rule: rule, message: message)
+        end
+
+        def push_diagnostic(node, severity:, rule:, message:)
+          location = node.location
+          @diagnostics << Rigor::Analysis::Diagnostic.new(
+            path: @path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: message,
+            severity: severity,
+            rule: rule
+          )
+        end
+      end
+    end
+  end
+end