rigortype 0.1.9 → 0.1.11

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class Sidekiq < Rigor::Plugin::Base
+      # Walks a parsed file's AST looking for
+      # `<WorkerClass>.perform_async(...)` /
+      # `.perform_inline(...)` / `.perform_in(time, ...)` /
+      # `.perform_at(time, ...)` calls and validates each
+      # against the {WorkerIndex}.
+      #
+      # Argument-shape rules:
+      #
+      # - `perform_async` / `perform_inline` — every
+      #   argument is forwarded to `#perform`. Validate
+      #   `actual == #perform.arity`.
+      # - `perform_in(interval, ...args)` /
+      #   `perform_at(time, ...args)` — the FIRST argument
+      #   is the schedule (a Time / Integer / ActiveSupport
+      #   duration); the rest are forwarded to `#perform`.
+      #   Validate `actual_args - 1 == #perform.arity`.
+      module Analyzer
+        # Methods that delegate to `#perform` 1:1.
+        DIRECT_ENTRY_METHODS = %i[perform_async perform_inline].freeze
+
+        # Methods whose first argument is a schedule (the
+        # remaining args are forwarded to `#perform`).
+        SCHEDULED_ENTRY_METHODS = %i[perform_in perform_at].freeze
+
+        ENTRY_METHODS = (DIRECT_ENTRY_METHODS + SCHEDULED_ENTRY_METHODS).freeze
+
+        Diagnostic = Struct.new(:path, :line, :column, :severity, :rule, :message, keyword_init: true)
+
+        module_function
+
+        # @param path [String]
+        # @param root [Prism::Node]
+        # @param worker_index [WorkerIndex]
+        # @return [Array<Diagnostic>]
+        def diagnose(path:, root:, worker_index:)
+          diagnostics = []
+          walk(root) do |call_node|
+            class_name = constant_receiver_name(call_node.receiver)
+            next if class_name.nil?
+
+            entry = worker_index.find(class_name) || worker_index.find("::#{class_name}")
+            next if entry.nil?
+
+            diagnostics << info_diagnostic(path, call_node, entry)
+            arity_diag = arity_check(path, call_node, entry)
+            diagnostics << arity_diag if arity_diag
+          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: "worker-call",
+            message: "`#{entry.class_name}.#{call_node.name}` matches `#perform` " \
+                     "(arity #{entry.arity_label})"
+          )
+        end
+
+        def arity_check(path, call_node, entry)
+          all_args = (call_node.arguments&.arguments || []).size
+          # Scheduled entries consume the first arg as the
+          # schedule; the rest are forwarded.
+          forwarded_count = SCHEDULED_ENTRY_METHODS.include?(call_node.name) ? all_args - 1 : all_args
+
+          if SCHEDULED_ENTRY_METHODS.include?(call_node.name) && all_args.zero?
+            return missing_schedule_diagnostic(path, call_node, entry)
+          end
+
+          return nil if forwarded_count.negative?
+          return nil if entry.accepts?(forwarded_count)
+
+          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 " \
+                     "#{describe_expected(entry, call_node.name)} forwarded to `#perform` " \
+                     "(arity #{entry.arity_label}), got #{forwarded_count}"
+          )
+        end
+
+        def missing_schedule_diagnostic(path, call_node, entry)
+          location = call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :error,
+            rule: "missing-schedule",
+            message: "`#{entry.class_name}.#{call_node.name}` requires a schedule " \
+                     "(time / interval) as its first argument, got 0 arguments"
+          )
+        end
+
+        def describe_expected(entry, method_name)
+          if SCHEDULED_ENTRY_METHODS.include?(method_name)
+            "#{entry.arity_label} argument(s) (after the schedule)"
+          else
+            "#{entry.arity_label} argument(s)"
+          end
+        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-sidekiq/lib/rigor/plugin/sidekiq/worker_discoverer.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "worker_index"
+
+module Rigor
+  module Plugin
+    class Sidekiq < Rigor::Plugin::Base
+      # Walks the configured worker-search paths via the
+      # plugin's `IoBoundary`, parses each `.rb` file with
+      # Prism, and collects classes that `include
+      # Sidekiq::Job` (or one of the configured marker
+      # modules). 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 `include` matches against the
+      #   configured marker modules. `class MyWorker;
+      #   include Concerns::Sidekiqable; end` where
+      #   `Concerns::Sidekiqable` re-includes `Sidekiq::Job`
+      #   is NOT discovered. Add the intermediate module to
+      #   `worker_marker_modules` if needed.
+      # - The qualified class name is the lexical path
+      #   (`Admin::WelcomeWorker` for a class declared
+      #   inside `module Admin`).
+      # - `#perform` arity is read from the syntactic
+      #   parameter list. Methods built via
+      #   `define_method` are out of scope.
+      class WorkerDiscoverer
+        def initialize(io_boundary:, search_paths:, marker_modules:)
+          @io_boundary = io_boundary
+          @search_paths = search_paths
+          @marker_modules = marker_modules.to_set
+        end
+
+        # @return [WorkerIndex]
+        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_workers(tree, []) do |class_name, perform_def|
+              entries << build_entry(class_name, perform_def)
+            end
+          end
+          WorkerIndex.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_workers(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_workers(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("::")
+          if includes_marker_module?(node.body)
+            perform_def = lookup_perform_def(node.body)
+            yield full_name, perform_def
+          end
+
+          inner_path = lexical_path + [class_local_name]
+          walk_for_workers(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_workers(node.body, inner_path, &) if node.body
+        end
+
+        # Returns true if the class body contains a top-level
+        # `include <Module>` call where `<Module>` matches
+        # one of the configured marker modules.
+        def includes_marker_module?(body)
+          return false if body.nil?
+
+          body.compact_child_nodes.any? do |node|
+            next false unless node.is_a?(Prism::CallNode)
+            next false unless node.name == :include
+            next false unless node.receiver.nil?
+
+            arg = node.arguments&.arguments&.first
+            module_name = constant_path_name(arg)
+            module_name && @marker_modules.include?(module_name)
+          end
+        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 perform(...)` node
+        # from a class body, or `nil` when the class doesn't
+        # override `#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 `WorkerIndex::Entry` from the discovered
+        # class's `#perform` def. When the class doesn't
+        # override `#perform`, we record an "any-arity"
+        # entry — Sidekiq itself doesn't supply a default
+        # `#perform`, so calling `perform_async` on a
+        # worker without one is 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 WorkerIndex::Entry.new(
+              class_name: class_name, min_arity: 0,
+              max_arity: Float::INFINITY
+            )
+          end
+
+          parameters = perform_def.parameters
+          if parameters.nil?
+            return WorkerIndex::Entry.new(
+              class_name: class_name, min_arity: 0, max_arity: 0
+            )
+          end
+
+          required_count = (parameters.requireds || []).size
+          optional_count = (parameters.optionals || []).size
+          rest_present = !parameters.rest.nil?
+
+          WorkerIndex::Entry.new(
+            class_name: class_name,
+            min_arity: required_count,
+            max_arity: rest_present ? Float::INFINITY : required_count + optional_count
+          )
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/worker_index.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    class Sidekiq < Rigor::Plugin::Base
+      # Frozen catalogue of discovered Sidekiq worker
+      # classes keyed by qualified class name. Each entry
+      # holds the `#perform` method's arity envelope so the
+      # analyzer can validate `Worker.perform_async(...)`
+      # call sites.
+      #
+      # Same envelope shape as `rigor-activejob`'s
+      # `JobIndex::Entry`: `min_arity` / `max_arity` form a
+      # closed range (`Float::INFINITY` for the upper bound
+      # when `*args` is present).
+      class WorkerIndex
+        Entry = Data.define(:class_name, :min_arity, :max_arity) 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
+
+        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-sidekiq/lib/rigor/plugin/sidekiq.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "sidekiq/worker_index"
+require_relative "sidekiq/worker_discoverer"
+require_relative "sidekiq/analyzer"
+
+module Rigor
+  module Plugin
+    # rigor-sidekiq — validates `Worker.perform_async(...)`
+    # / `.perform_in(...)` / `.perform_at(...)` /
+    # `.perform_inline(...)` argument arity against the
+    # discovered `#perform` definitions.
+    #
+    # Tier 3C of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
+    # Statically discovers Sidekiq workers by walking
+    # `worker_search_paths` and parsing each file with
+    # Prism — no `sidekiq` runtime dependency.
+    #
+    # ## Configuration
+    #
+    #     plugins:
+    #       - gem: rigor-sidekiq
+    #         config:
+    #           worker_search_paths: ["app/workers", "app/sidekiq"]   # default; optional
+    #           worker_marker_modules: ["Sidekiq::Job", "Sidekiq::Worker"]  # default; optional
+    #
+    # ## What it checks
+    #
+    # 1. **Argument arity** — `perform_async(args)` /
+    #    `perform_inline(args)` forward every argument to
+    #    `#perform`; `perform_in(t, args)` /
+    #    `perform_at(t, args)` consume the first argument
+    #    as the schedule and forward the rest. Mismatches
+    #    emit `wrong-arity`.
+    # 2. **Missing schedule** — `perform_in()` /
+    #    `perform_at()` with zero arguments emit
+    #    `missing-schedule`.
+    #
+    # ## Limitations (v0.1.0)
+    #
+    # - Direct `include` matches only against the
+    #   configured marker modules. Indirect includes via a
+    #   custom concern are out of scope.
+    # - `#perform` arity is read from the syntactic
+    #   parameter list. `define_method` actions are out of
+    #   scope.
+    # - Required keyword arguments are not validated at
+    #   the call site (positional-only for v0.1.0). Sidekiq
+    #   serialises arguments to JSON, so keyword args are
+    #   uncommon in practice.
+    # - The schedule argument's type isn't validated (no
+    #   "is this a Time?" check); we just consume it.
+    class Sidekiq < Rigor::Plugin::Base
+      manifest(
+        id: "sidekiq",
+        version: "0.1.0",
+        description: "Validates Sidekiq `Worker.perform_async` argument arity.",
+        config_schema: {
+          "worker_search_paths" => :array,
+          "worker_marker_modules" => :array
+        }
+      )
+
+      DEFAULT_WORKER_SEARCH_PATHS = ["app/workers", "app/sidekiq"].freeze
+      DEFAULT_WORKER_MARKER_MODULES = %w[Sidekiq::Job Sidekiq::Worker].freeze
+
+      producer :worker_index do |_params|
+        WorkerDiscoverer.new(
+          io_boundary: io_boundary,
+          search_paths: @worker_search_paths,
+          marker_modules: @worker_marker_modules
+        ).discover
+      end
+
+      def init(_services)
+        @worker_search_paths = Array(config.fetch("worker_search_paths", DEFAULT_WORKER_SEARCH_PATHS)).map(&:to_s)
+        @worker_marker_modules = Array(
+          config.fetch("worker_marker_modules", DEFAULT_WORKER_MARKER_MODULES)
+        ).map(&:to_s)
+        @worker_index = nil
+        @load_error = nil
+      end
+
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        index = worker_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, worker_index: index).map { |diag| build_diagnostic(diag) }
+      end
+
+      private
+
+      def worker_index_or_nil
+        return @worker_index if @worker_index
+
+        @worker_index = cache_for(:worker_index, params: {}).call
+      rescue StandardError => e
+        @load_error = "rigor-sidekiq: failed to discover workers: #{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(Sidekiq)
+  end
+end

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

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

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    # ADR-16 Tier A worked plugin: recognises Sinatra's class-
+    # level route DSL.
+    #
+    # Sinatra's modular style:
+    #
+    #     class MyApp < Sinatra::Base
+    #       get "/hello" do
+    #         "Hello #{params['name']}"
+    #       end
+    #
+    #       post "/bye" do
+    #         halt 403 if params["forbidden"]
+    #         redirect "/landing"
+    #       end
+    #     end
+    #
+    # At runtime `Sinatra::Base#generate_method`
+    # (`lib/sinatra/base.rb:1788-1793`) does `define_method(name,
+    # &block); remove_method`, turning each block into a real
+    # instance method of the user's app class. The substrate's
+    # Tier A hook (`Rigor::Inference::MacroBlockSelfType`)
+    # replays the same contract statically: the block runs with
+    # `self : Nominal[MyApp]`, so bare identifiers (`params`,
+    # `redirect`, `halt`, `session`, `headers`, `content_type`,
+    # `body`, `status`, `erb`, …) resolve through
+    # `Sinatra::Base`'s RBS via rigor's normal inference path.
+    #
+    # ## Reach
+    #
+    # All nine class-level HTTP verb methods Sinatra exposes:
+    # `get`, `post`, `put`, `delete`, `head`, `options`, `patch`,
+    # `link`, `unlink` (`lib/sinatra/base.rb:1531-1553`). Both
+    # modular-style subclasses of `Sinatra::Base` and `Sinatra::Application`
+    # (classic top-level style, when used via `class App <
+    # Sinatra::Application`) match because the receiver
+    # constraint accepts every subclass.
+    #
+    # ## What the plugin does NOT do (yet)
+    #
+    # - **Routing diagnostics.** Path uniqueness, conflict
+    #   detection, named-route reverse lookup — none of these
+    #   are in slice 1c's scope.
+    # - **Custom helpers.** `helpers do ... end` blocks that
+    #   inject module methods into the app's instance namespace
+    #   are Tier C / Tier B work, not Tier A.
+    # - **Configure / settings.** `configure do ... end` and
+    #   `set :session_secret, "..."` are settings DSL, not
+    #   route DSL — handled by separate substrate entries when
+    #   demand surfaces.
+    # - **Classic-style top-level routes.** A bare
+    #   `get '/path' do ... end` at the top of a script (no
+    #   enclosing `class < Sinatra::Base`) is the classic-mode
+    #   pattern (`lib/sinatra/main.rb`). Tier A as currently
+    #   wired requires the receiver's class to be visible at
+    #   the call site; a top-level call's receiver is the
+    #   classic-mode `Sinatra::Application`, which the
+    #   `Sinatra::Delegator` mixin forwards from `main`. The
+    #   classic style is deferred until the demand justifies
+    #   the extra match shape.
+    #
+    # See `plugins/rigor-sinatra/README.md` for usage and the
+    # demo script under `plugins/rigor-sinatra/demo/`.
+    class Sinatra < Rigor::Plugin::Base
+      manifest(
+        id: "sinatra",
+        version: "0.1.0",
+        description: "Recognises Sinatra's class-level route DSL via ADR-16 Tier A.",
+        block_as_methods: [
+          Rigor::Plugin::Macro::BlockAsMethod.new(
+            receiver_constraint: "Sinatra::Base",
+            verbs: %i[get post put delete head options patch link unlink]
+          )
+        ]
+      )
+    end
+
+    Rigor::Plugin.register(Sinatra)
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Gem entry point. Required by Rigor's plugin loader when
+# `.rigor.yml` lists `rigor-sinatra` under `plugins:`. The
+# loader expects this `require` to side-effect a call to
+# `Rigor::Plugin.register`, which the body of
+# `lib/rigor/plugin/sinatra.rb` performs at load time.
+require_relative "rigor/plugin/sinatra"