rigortype 0.1.9 → 0.1.11

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+require "prism"
+
+module Rigor
+  module Plugin
+    class Actioncable < Rigor::Plugin::Base
+      # Walks a parsed file's AST looking for ActionCable
+      # entry-point calls and validates each against the
+      # {ChannelIndex}.
+      #
+      # Recognised shapes:
+      #
+      # - `<ChannelClass>.broadcast_to(record, data)` —
+      #   class-targeted broadcast. The class must exist in
+      #   the index.
+      # - `ActionCable.server.broadcast(stream_name, data)`
+      #   — string-targeted broadcast. When `stream_name`
+      #   is a literal string and the index has at least
+      #   one channel with no dynamic stream registrations,
+      #   we check that the name appears in
+      #   `index.all_stream_names`. Otherwise the
+      #   `unknown-stream` warning is suppressed (we can't
+      #   prove absence).
+      module Analyzer
+        # `ActionCable.server.broadcast(...)` — the receiver
+        # path we recognise as a server-targeted broadcast.
+        # Single-symbol form (just `broadcast`) is too
+        # ambiguous to validate.
+        SERVER_BROADCAST_RECEIVER_NAMES = %w[
+          ActionCable.server
+          ::ActionCable.server
+        ].freeze
+
+        Diagnostic = Struct.new(:path, :line, :column, :severity, :rule, :message, keyword_init: true)
+
+        module_function
+
+        # @param path [String]
+        # @param root [Prism::Node]
+        # @param channel_index [ChannelIndex]
+        # @return [Array<Diagnostic>]
+        def diagnose(path:, root:, channel_index:)
+          diagnostics = []
+          walk(root) do |call_node|
+            case call_node.name
+            when :broadcast_to
+              diagnostics.concat(analyse_broadcast_to(path, call_node, channel_index))
+            when :broadcast
+              diagnostics.concat(analyse_server_broadcast(path, call_node, channel_index))
+            end
+          end
+          diagnostics
+        end
+
+        def walk(node, &)
+          return unless node.is_a?(Prism::Node)
+
+          yield node if node.is_a?(Prism::CallNode)
+          node.compact_child_nodes.each { |child| walk(child, &) }
+        end
+
+        def analyse_broadcast_to(path, call_node, channel_index)
+          class_name = constant_receiver_name(call_node.receiver)
+          return [] if class_name.nil?
+
+          # broadcast_to with a class-name receiver that
+          # doesn't end in "Channel" is almost certainly
+          # not ActionCable — pass through silently to
+          # avoid flagging unrelated `broadcast_to` methods.
+          return [] unless class_name.end_with?("Channel")
+
+          entry = channel_index.find(class_name) || channel_index.find("::#{class_name}")
+          return [unknown_channel_diagnostic(path, call_node, class_name, channel_index)] if entry.nil?
+
+          [broadcast_target_info(path, call_node, entry)]
+        end
+
+        def analyse_server_broadcast(path, call_node, channel_index)
+          receiver_path = call_chain_string(call_node.receiver)
+          return [] unless SERVER_BROADCAST_RECEIVER_NAMES.include?(receiver_path)
+
+          args = call_node.arguments&.arguments || []
+          stream_arg = args.first
+          return [] if stream_arg.nil?
+          return [] unless stream_arg.is_a?(Prism::StringNode)
+          return [] if channel_index.any_dynamic_streams?
+
+          stream_name = stream_arg.unescaped
+          if channel_index.all_stream_names.include?(stream_name)
+            return [server_broadcast_info(path, call_node, stream_name)]
+          end
+
+          [unknown_stream_diagnostic(path, call_node, stream_name, channel_index)]
+        end
+
+        def broadcast_target_info(path, call_node, entry)
+          location = call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :info,
+            rule: "broadcast-target",
+            message: "`#{entry.class_name}.broadcast_to(...)` matches discovered channel"
+          )
+        end
+
+        def server_broadcast_info(path, call_node, stream_name)
+          location = call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :info,
+            rule: "broadcast-stream",
+            message: "`broadcast(\"#{stream_name}\", ...)` matches a registered `stream_from`"
+          )
+        end
+
+        def unknown_channel_diagnostic(path, call_node, class_name, channel_index)
+          location = call_node.location
+          suggestions = DidYouMean::SpellChecker.new(dictionary: channel_index.names).correct(class_name)
+          suggestion_part = suggestions.empty? ? "" : " (did you mean `#{suggestions.first}`?)"
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :error,
+            rule: "unknown-channel",
+            message: "no ActionCable channel `#{class_name}`#{suggestion_part}"
+          )
+        end
+
+        def unknown_stream_diagnostic(path, call_node, stream_name, channel_index)
+          location = call_node.location
+          dictionary = channel_index.all_stream_names.to_a
+          suggestions = DidYouMean::SpellChecker.new(dictionary: dictionary).correct(stream_name)
+          suggestion_part = suggestions.empty? ? "" : " (did you mean `\"#{suggestions.first}\"`?)"
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :warning,
+            rule: "unknown-stream",
+            message: "no `stream_from \"#{stream_name}\"` registration in any discovered " \
+                     "channel#{suggestion_part}"
+          )
+        end
+
+        # Renders an `A.b.c` chain as a string (used to
+        # detect `ActionCable.server`). Returns nil for
+        # non-chained nodes.
+        def call_chain_string(node)
+          parts = []
+          current = node
+          while current.is_a?(Prism::CallNode) && current.arguments.nil?
+            parts.unshift(current.name.to_s)
+            current = current.receiver
+          end
+          base = constant_receiver_name(current)
+          return nil if base.nil? || parts.empty?
+
+          [base, *parts].join(".")
+        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-actioncable/lib/rigor/plugin/actioncable/channel_discoverer.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "channel_index"
+
+module Rigor
+  module Plugin
+    class Actioncable < Rigor::Plugin::Base
+      # Walks the configured channel-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 channel, the discoverer:
+      #
+      # - Records every public instance-side `def` whose
+      #   name isn't an ActionCable framework hook
+      #   (`subscribed`, `unsubscribed`, `_`-prefixed).
+      #   These are the action methods clients can invoke
+      #   via `subscription.perform("action_name", data)`.
+      # - Records every literal-string `stream_from "name"`
+      #   call as a registered stream name.
+      # - Sets `dynamic_streams: true` when the channel has
+      #   ANY non-literal `stream_from` argument (or a
+      #   `stream_for` call) so the analyzer knows it can't
+      #   be sure of every stream name.
+      #
+      # Limitations (intentional for v0.1.0):
+      #
+      # - Direct-superclass match only.
+      # - Public-vs-private is not tracked; the framework
+      #   hooks (`subscribed`/`unsubscribed`) are excluded
+      #   by name. Methods marked `private` after a
+      #   `private` keyword would still appear in the
+      #   `action_methods` set.
+      # - `stream_for(record)` (model-scoped streams) is
+      #   recognised as setting `dynamic_streams: true` but
+      #   not introspected further.
+      class ChannelDiscoverer
+        FRAMEWORK_HOOKS = %i[subscribed unsubscribed].to_set.freeze
+
+        def initialize(io_boundary:, search_paths:, base_classes:)
+          @io_boundary = io_boundary
+          @search_paths = search_paths
+          @base_classes = base_classes.to_set
+        end
+
+        # @return [ChannelIndex]
+        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_channels(tree, []) do |class_name, body|
+              entries << build_entry(class_name, path, body)
+            end
+          end
+          ChannelIndex.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_channels(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_channels(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
+          yield full_name, node.body if superclass && @base_classes.include?(superclass)
+
+          inner_path = lexical_path + [class_local_name]
+          walk_for_channels(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_channels(node.body, inner_path, &) if node.body
+        end
+
+        def build_entry(class_name, path, body)
+          actions = []
+          (body&.compact_child_nodes || []).each do |node|
+            actions << node.name if node.is_a?(Prism::DefNode) && action_def?(node)
+          end
+
+          stream_names, dynamic_streams = collect_stream_registrations(body)
+
+          ChannelIndex::Entry.new(
+            class_name: class_name,
+            file_path: path,
+            action_methods: actions.to_set.freeze,
+            stream_names: stream_names.to_set.freeze,
+            dynamic_streams: dynamic_streams
+          )
+        end
+
+        # Walks the channel body recursively (so
+        # `stream_from` / `stream_for` calls inside
+        # `subscribed` / helper methods are picked up).
+        # Returns `[Array<String>, bool]` — the literal
+        # stream names + whether any dynamic registration
+        # was seen.
+        def collect_stream_registrations(node, names: [], dynamic: false)
+          return [names, dynamic] if node.nil?
+
+          if node.is_a?(Prism::CallNode) && node.receiver.nil?
+            case node.name
+            when :stream_from
+              arg = node.arguments&.arguments&.first
+              if arg.is_a?(Prism::StringNode)
+                names << arg.unescaped
+              else
+                dynamic = true
+              end
+            when :stream_for
+              # Model-scoped stream — name is computed from
+              # the record at runtime; treat as dynamic.
+              dynamic = true
+            end
+          end
+
+          node.compact_child_nodes.each do |child|
+            names, dynamic = collect_stream_registrations(child, names: names, dynamic: dynamic)
+          end
+          [names, dynamic]
+        end
+
+        def action_def?(node)
+          return false if node.receiver.is_a?(Prism::SelfNode)
+          return false if FRAMEWORK_HOOKS.include?(node.name)
+          return false if node.name.to_s.start_with?("_")
+
+          true
+        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
+      end
+    end
+  end
+end

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable/channel_index.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    class Actioncable < Rigor::Plugin::Base
+      # Frozen catalogue of discovered ActionCable channel
+      # classes keyed by qualified class name. Each entry
+      # holds:
+      #
+      # - `action_methods` — the set of public instance
+      #   methods that aren't ActionCable framework hooks
+      #   (`subscribed` / `unsubscribed`). These are the
+      #   methods clients invoke via
+      #   `subscription.perform("action_name", data)`.
+      # - `stream_names` — the set of literal-string stream
+      #   names registered via `stream_from "name"` calls
+      #   inside the channel body. Dynamic registrations
+      #   (`stream_from interpolated_string`) are recorded
+      #   separately as `dynamic_streams: true` so the
+      #   analyzer can suppress unknown-stream warnings on
+      #   any channel that has at least one dynamic
+      #   registration.
+      class ChannelIndex
+        Entry = Data.define(:class_name, :file_path, :action_methods, :stream_names, :dynamic_streams) do
+          def includes_action?(name)
+            action_methods.include?(name.to_sym)
+          end
+
+          def known_actions
+            action_methods.to_a.sort
+          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
+
+        # All literal stream names registered across every
+        # discovered channel.
+        def all_stream_names
+          @entries.flat_map { |e| e.stream_names.to_a }.to_set
+        end
+
+        # True when at least one discovered channel uses a
+        # dynamic stream registration. The analyzer treats
+        # this as "we can't be sure any literal name is
+        # missing" and downgrades unknown-stream from
+        # `:warning` to `:info` (or drops it entirely;
+        # current behaviour: skip warnings).
+        def any_dynamic_streams?
+          @entries.any?(&:dynamic_streams)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "actioncable/channel_index"
+require_relative "actioncable/channel_discoverer"
+require_relative "actioncable/analyzer"
+
+module Rigor
+  module Plugin
+    # rigor-actioncable — validates ActionCable
+    # `<Channel>.broadcast_to(...)` and
+    # `ActionCable.server.broadcast(stream_name, ...)`
+    # call sites against the discovered channel index.
+    #
+    # Tier 3F of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
+    # Statically discovers channel classes by walking
+    # `channel_search_paths` and parsing each file with
+    # Prism — no `actioncable` runtime dependency.
+    #
+    # ## Configuration
+    #
+    #     plugins:
+    #       - gem: rigor-actioncable
+    #         config:
+    #           channel_search_paths: ["app/channels"]                                # default; optional
+    #           channel_base_classes: ["ApplicationCable::Channel", "ActionCable::Channel::Base"]  # default; optional
+    #
+    # ## What it checks
+    #
+    # 1. **Channel class existence** — `<X>.broadcast_to(...)`
+    #    where `X` ends in `Channel` must resolve to a
+    #    discovered channel.
+    # 2. **Stream-name registration** —
+    #    `ActionCable.server.broadcast("stream_name", ...)`
+    #    with a literal stream name is checked against
+    #    every discovered channel's `stream_from "..."`
+    #    registrations. The check is suppressed when ANY
+    #    discovered channel uses a dynamic registration
+    #    (`stream_from interpolated_string` or
+    #    `stream_for record`) — the absence of a literal
+    #    match doesn't prove absence.
+    #
+    # ## Limitations (v0.1.0)
+    #
+    # - **Direct-superclass match only.** Indirect
+    #   inheritance (`AdminChannel < BaseChannel <
+    #   ApplicationCable::Channel`) needs `BaseChannel`
+    #   listed in `channel_base_classes`.
+    # - **Action method invocations are not validated.**
+    #   ActionCable actions are invoked from JS via
+    #   `subscription.perform("action_name", data)`; we
+    #   don't analyse JS so the action-method index is
+    #   currently informational only (future cross-plugin
+    #   handoff to a hypothetical JS-side analyzer).
+    # - **`broadcast_to` arity isn't checked.** The method
+    #   takes any record + any data hash; there's no
+    #   useful arity envelope.
+    class Actioncable < Rigor::Plugin::Base
+      manifest(
+        id: "actioncable",
+        version: "0.1.0",
+        description: "Validates ActionCable broadcast call shape against discovered channels.",
+        config_schema: {
+          "channel_search_paths" => :array,
+          "channel_base_classes" => :array
+        }
+      )
+
+      DEFAULT_CHANNEL_SEARCH_PATHS = ["app/channels"].freeze
+      DEFAULT_CHANNEL_BASE_CLASSES = [
+        "ApplicationCable::Channel",
+        "ActionCable::Channel::Base"
+      ].freeze
+
+      producer :channel_index do |_params|
+        ChannelDiscoverer.new(
+          io_boundary: io_boundary,
+          search_paths: @channel_search_paths,
+          base_classes: @channel_base_classes
+        ).discover
+      end
+
+      def init(_services)
+        @channel_search_paths = Array(
+          config.fetch("channel_search_paths", DEFAULT_CHANNEL_SEARCH_PATHS)
+        ).map(&:to_s)
+        @channel_base_classes = Array(
+          config.fetch("channel_base_classes", DEFAULT_CHANNEL_BASE_CLASSES)
+        ).map(&:to_s)
+        @channel_index = nil
+        @load_error = nil
+      end
+
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        index = channel_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, channel_index: index).map { |diag| build_diagnostic(diag) }
+      end
+
+      private
+
+      def channel_index_or_nil
+        return @channel_index if @channel_index
+
+        # Pass an explicit descriptor covering every `.rb` file
+        # under the configured channel search paths so the cache
+        # invalidates when channels are added, removed, or edited.
+        # Without it the auto-built descriptor depends on the
+        # `IoBoundary`'s in-process read history — empty on the
+        # first call of a fresh process, so warm cache hits would
+        # serve stale `ChannelIndex` data when project files have
+        # changed between sessions.
+        descriptor = glob_descriptor(@channel_search_paths, "**/*.rb")
+        @channel_index = cache_for(:channel_index, params: {}, descriptor: descriptor).call
+      rescue StandardError => e
+        @load_error = "rigor-actioncable: failed to discover channels: #{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(Actioncable)
+  end
+end

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

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