ripple_effect 0.1.0

data/lib/ripple_effect/extractors/rails_jobs.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Extracts Active Job enqueue sites.
+    #
+    # `InvoiceJob.perform_later(id)` runs `InvoiceJob#perform` later, in another
+    # process. Nothing in the call graph says so, which is exactly why a change to
+    # `perform` surprises people. No queue or adapter is ever loaded.
+    class RailsJobs < Base
+      ENQUEUE_METHODS = %w[perform_later perform_now].freeze
+
+      # `InvoiceJob.set(wait: 5.minutes).perform_later`: the constant is still
+      # visible through the chained call.
+      CHAIN_METHODS = %w[set].freeze
+
+      JOB_SUPERCLASSES = %w[ApplicationJob ActiveJob::Base].freeze
+
+      def self.feature = :jobs
+
+      def extract
+        mark_job_classes
+        link_enqueue_sites
+      end
+
+      private
+
+      # Job classes get their own node kind so risk scoring can see that a change
+      # is reachable from background work.
+      def mark_job_classes
+        index.declarations.select(&:namespace?).each do |declaration|
+          next unless job_class?(declaration)
+
+          perform = node_for("#{declaration.qualified_name}#perform")
+          next unless perform
+
+          job_node = add_node(
+            Node.new(
+              kind: :job,
+              # Distinguished from the plain class node of the same name, which
+              # exists too and means something different.
+              name: "#{declaration.qualified_name} (job)",
+              qualified_name: "job:#{declaration.qualified_name}",
+              path: declaration.path,
+              start_line: declaration.start_line,
+              end_line: declaration.end_line,
+              metadata: { "class" => declaration.qualified_name }
+            )
+          )
+
+          add_edge(
+            from: job_node, into: perform, type: :job_enqueue,
+            evidence: "rails.job_perform", confidence: Confidence::HIGH,
+            location: job_node.location
+          )
+        end
+      end
+
+      def job_class?(declaration)
+        return true if JOB_SUPERCLASSES.include?(declaration.superclass_name)
+        return false if declaration.superclass_name.nil?
+
+        # ApplicationJob itself is usually the only direct ActiveJob::Base subclass;
+        # everything else inherits from it, possibly through another layer.
+        ancestor_is_job?(declaration.superclass_name, depth: 0)
+      end
+
+      def ancestor_is_job?(name, depth:)
+        return false if depth > 5 || name.nil?
+        return true if JOB_SUPERCLASSES.include?(name)
+
+        parent = namespaces_by_name[name]
+        parent && ancestor_is_job?(parent.superclass_name, depth: depth + 1)
+      end
+
+      def link_enqueue_sites
+        project.source_paths.each do |path|
+          each_node(sources.ast(path)) do |node|
+            next unless node.is_a?(Prism::CallNode)
+            next unless ENQUEUE_METHODS.include?(node.name.to_s)
+
+            constant = receiver_constant(node.receiver)
+            next unless constant
+
+            link_enqueue(constant, node, path)
+          end
+        end
+      end
+
+      # Unwraps `Job.set(...)` to find the constant underneath.
+      def receiver_constant(receiver)
+        case receiver
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          constant_path_name(receiver)
+        when Prism::CallNode
+          CHAIN_METHODS.include?(receiver.name.to_s) ? receiver_constant(receiver.receiver) : nil
+        end
+      end
+
+      def link_enqueue(constant, call, path)
+        target = node_for("#{constant}#perform")
+        line = call.location.start_line
+
+        if target.nil?
+          add_diagnostic(
+            code: "unresolved_method_receiver",
+            severity: :info,
+            path: path,
+            line: line,
+            message: "#{constant}.#{call.name} enqueues a job whose #perform is not indexed"
+          )
+          return
+        end
+
+        add_edge(
+          from: enclosing_node(path, line), into: target,
+          type: :job_enqueue, evidence: "rails.#{call.name}",
+          confidence: Confidence::HIGH, location: location_for(path, line),
+          metadata: { "job" => constant, "enqueue" => call.name.to_s }
+        )
+      end
+
+      def enclosing_node(path, line)
+        declaration = index.declaration_at(path: path, line: line)
+        (declaration && node_for(declaration.qualified_name)) || file_node_for(path)
+      end
+    end
+  end
+end

data/lib/ripple_effect/extractors/rails_mailers.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Extracts Action Mailer deliveries.
+    #
+    # `OrderMailer.receipt(order).deliver_later` reaches `OrderMailer#receipt`
+    # through a class-level call that exists nowhere in the source: Action Mailer
+    # synthesises it from the instance method.
+    class RailsMailers < Base
+      DELIVERY_METHODS = %w[deliver_later deliver_now deliver_later! deliver_now!].freeze
+      MAILER_SUPERCLASSES = %w[ApplicationMailer ActionMailer::Base].freeze
+
+      def self.feature = :mailers
+
+      def extract
+        mark_mailer_actions
+        link_deliveries
+      end
+
+      private
+
+      def mark_mailer_actions
+        mailer_classes.each do |declaration|
+          methods_by_owner.fetch(declaration.qualified_name, []).each do |candidate|
+            action = candidate.qualified_name.split("#").last
+            action_node = add_node(
+              Node.new(
+                kind: :mailer_action,
+                name: "#{declaration.qualified_name}.#{action}",
+                qualified_name: "mailer:#{declaration.qualified_name}.#{action}",
+                path: candidate.path,
+                start_line: candidate.start_line,
+                end_line: candidate.end_line,
+                metadata: { "mailer" => declaration.qualified_name, "action" => action }
+              )
+            )
+
+            add_edge(
+              from: action_node, into: node_for(candidate.qualified_name),
+              type: :mailer_delivery, evidence: "rails.mailer_action",
+              confidence: Confidence::HIGH, location: action_node.location
+            )
+          end
+        end
+      end
+
+      # Instance methods grouped by the class that owns them, built once.
+      def methods_by_owner
+        @methods_by_owner ||= index.declarations
+                                   .select { |d| d.kind == :instance_method && d.owner_name }
+                                   .group_by(&:owner_name)
+      end
+
+      def mailer_classes
+        @mailer_classes ||= index.declarations.select do |declaration|
+          declaration.namespace? && mailer_class?(declaration)
+        end
+      end
+
+      def mailer_class?(declaration, depth: 0)
+        name = declaration.superclass_name
+        return false if name.nil? || depth > 5
+        return true if MAILER_SUPERCLASSES.include?(name)
+
+        parent = namespaces_by_name[name]
+        parent ? mailer_class?(parent, depth: depth + 1) : false
+      end
+
+      def link_deliveries
+        project.source_paths.each do |path|
+          each_node(sources.ast(path)) do |node|
+            next unless node.is_a?(Prism::CallNode)
+            next unless DELIVERY_METHODS.include?(node.name.to_s)
+
+            link_delivery(node, path)
+          end
+        end
+      end
+
+      # The receiver of `.deliver_later` is the `OrderMailer.receipt(order)` call.
+      def link_delivery(call, path)
+        producer = call.receiver
+        return unless producer.is_a?(Prism::CallNode)
+
+        mailer = constant_path_name(producer.receiver)
+        return unless mailer
+
+        action = producer.name.to_s
+        line = call.location.start_line
+        target = node_for("#{mailer}##{action}")
+
+        if target.nil?
+          add_diagnostic(
+            code: "unresolved_method_receiver",
+            severity: :info,
+            path: path,
+            line: line,
+            message: "#{mailer}.#{action} is delivered here but the mailer action is not indexed"
+          )
+          return
+        end
+
+        add_edge(
+          from: enclosing_node(path, line), into: target,
+          type: :mailer_delivery, evidence: "rails.#{call.name}",
+          confidence: Confidence::HIGH, location: location_for(path, line),
+          metadata: { "mailer" => mailer, "action" => action, "delivery" => call.name.to_s }
+        )
+      end
+
+      def enclosing_node(path, line)
+        declaration = index.declaration_at(path: path, line: line)
+        (declaration && node_for(declaration.qualified_name)) || file_node_for(path)
+      end
+    end
+  end
+end

data/lib/ripple_effect/extractors/rails_routes.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Extracts the routing table from `config/routes.rb`.
+    #
+    # Conservative by design: reads the literal forms that make up the bulk of
+    # real routing files and stays silent about the rest. An unreadable route is a
+    # diagnostic; a misread one would misreport the HTTP surface.
+    class RailsRoutes < Base
+      VERBS = %w[get post put patch delete options head].freeze
+      RESOURCE_MACROS = %w[resources resource].freeze
+      SCOPE_MACROS = %w[namespace scope resources resource collection member scope_module].freeze
+
+      # The seven RESTful actions, in Rails' own order.
+      PLURAL_ACTIONS = %w[index create new edit show update destroy].freeze
+      SINGULAR_ACTIONS = %w[create new edit show update destroy].freeze
+
+      # Which verb Rails maps each RESTful action to, for display.
+      ACTION_VERBS = {
+        "index" => "GET", "create" => "POST", "new" => "GET", "edit" => "GET",
+        "show" => "GET", "update" => "PATCH", "destroy" => "DELETE"
+      }.freeze
+
+      # Accumulated routing context as we descend through namespace/scope blocks.
+      Scope = Struct.new(:path_prefix, :module_prefix, keyword_init: true) do
+        def with(path: nil, module_name: nil)
+          Scope.new(
+            path_prefix: path ? [path_prefix, path].compact.reject(&:empty?).join("/") : path_prefix,
+            module_prefix: module_name ? [module_prefix, module_name].compact.reject(&:empty?).join("/") : module_prefix
+          )
+        end
+
+        def full_path(suffix)
+          "/#{[path_prefix, suffix].compact.reject(&:empty?).join('/').delete_prefix('/')}"
+        end
+
+        def controller_name(controller)
+          [module_prefix, controller].compact.reject(&:empty?).join("/")
+        end
+      end
+
+      def self.feature = :routes
+
+      def extract
+        routes_files.each do |path|
+          ast = sources.ast(path)
+          next unless ast
+
+          draw_block = find_draw_block(ast)
+          walk(draw_block || ast, Scope.new(path_prefix: nil, module_prefix: nil), path)
+        end
+      end
+
+      private
+
+      def routes_files
+        project.source_paths.select { |path| path == "config/routes.rb" || path.start_with?("config/routes/") }
+      end
+
+      # Everything interesting is inside `Rails.application.routes.draw`.
+      def find_draw_block(root)
+        found = nil
+
+        each_node(root) do |node|
+          next if found
+          next unless node.is_a?(Prism::CallNode)
+          next unless node.name.to_s == "draw" && node.block
+
+          found = node.block.body
+        end
+
+        found
+      end
+
+      def walk(node, scope, path)
+        return unless node
+
+        node.compact_child_nodes.each do |child|
+          if child.is_a?(Prism::CallNode)
+            handle_call(child, scope, path)
+          else
+            walk(child, scope, path)
+          end
+        end
+      end
+
+      def handle_call(call, scope, path)
+        name = call.name.to_s
+
+        if VERBS.include?(name)
+          add_verb_route(call, scope, path)
+        elsif RESOURCE_MACROS.include?(name)
+          add_resource_routes(call, scope, path)
+        elsif name == "namespace"
+          descend_namespace(call, scope, path)
+        elsif name == "scope"
+          descend_scope(call, scope, path)
+        elsif name == "root"
+          add_root_route(call, scope, path)
+        elsif call.block
+          walk(call.block.body, scope, path)
+        end
+      end
+
+      # `get "/health", to: "health#show"`
+      def add_verb_route(call, scope, path)
+        keywords = literal_keywords(call)
+        positional = literal_positional_names(call)
+        url = positional.first
+        target = keywords["to"] || implicit_target(positional)
+        return if url.nil? || target.nil? || !target.include?("#")
+
+        controller, action = target.split("#", 2)
+        register_route(
+          verb: call.name.to_s.upcase,
+          url: scope.full_path(url.delete_prefix("/")),
+          controller: scope.controller_name(controller),
+          action: action,
+          path: path,
+          line: call.location.start_line
+        )
+      end
+
+      # `get "health" => "health#show"` puts the target in the positional hash.
+      def implicit_target(positional)
+        positional.length >= 2 ? positional.last : nil
+      end
+
+      def add_root_route(call, scope, path)
+        target = literal_keywords(call)["to"] || literal_positional_names(call).first
+        return if target.nil? || !target.include?("#")
+
+        controller, action = target.split("#", 2)
+        register_route(
+          verb: "GET", url: scope.full_path(""),
+          controller: scope.controller_name(controller), action: action,
+          path: path, line: call.location.start_line
+        )
+      end
+
+      # `resources :orders, only: %i[index create]`
+      def add_resource_routes(call, scope, path)
+        name = literal_positional_names(call).first
+        return if name.nil?
+
+        keywords = literal_keywords(call)
+        macro = call.name.to_s
+        controller = keywords["controller"] || name
+        actions = resource_actions(macro, keywords)
+        segment = name
+
+        actions.each do |action|
+          register_route(
+            verb: ACTION_VERBS.fetch(action, "GET"),
+            url: scope.full_path(rest_path(segment, action, macro)),
+            controller: scope.controller_name(controller),
+            action: action,
+            path: path,
+            line: call.location.start_line
+          )
+        end
+
+        return unless call.block
+
+        # Nested resources inherit the parent's path prefix.
+        walk(call.block.body, scope.with(path: "#{segment}/:#{singularize(segment)}_id"), path)
+      end
+
+      def resource_actions(macro, keywords)
+        base = macro == "resource" ? SINGULAR_ACTIONS : PLURAL_ACTIONS
+        only = keywords["only"]
+        except = keywords["except"]
+
+        actions = base
+        actions &= Array(only).map(&:to_s) if only
+        actions -= Array(except).map(&:to_s) if except
+        actions
+      end
+
+      def rest_path(segment, action, macro)
+        member = macro == "resource" ? segment : "#{segment}/:id"
+
+        case action
+        when "index", "create" then segment
+        when "new" then "#{segment}/new"
+        when "edit" then "#{member}/edit"
+        else member
+        end
+      end
+
+      # `namespace :admin` prefixes both the URL and the controller module.
+      def descend_namespace(call, scope, path)
+        name = literal_positional_names(call).first
+        return unless name && call.block
+
+        walk(call.block.body, scope.with(path: name, module_name: name), path)
+      end
+
+      # `scope "/api"` prefixes the URL; `scope module: "api"` the controller module.
+      def descend_scope(call, scope, path)
+        return unless call.block
+
+        keywords = literal_keywords(call)
+        path_prefix = keywords["path"] || literal_positional_names(call).first
+
+        walk(call.block.body, scope.with(path: path_prefix, module_name: keywords["module"]), path)
+      end
+
+      def register_route(verb:, url:, controller:, action:, path:, line:)
+        controller_class = controller_class_name(controller)
+        target = node_for("#{controller_class}##{action}")
+
+        route_node = add_node(
+          Node.new(
+            kind: :route,
+            name: "#{verb} #{url}",
+            qualified_name: "route:#{verb}:#{url}",
+            path: path,
+            start_line: line,
+            end_line: line,
+            metadata: {
+              "verb" => verb, "url" => url, "controller" => controller_class, "action" => action
+            }
+          )
+        )
+
+        if target.nil?
+          add_diagnostic(
+            code: "unresolved_route_controller",
+            severity: :info,
+            path: path,
+            line: line,
+            message: "#{verb} #{url} routes to #{controller_class}##{action}, which is not indexed"
+          )
+          return
+        end
+
+        add_edge(
+          from: route_node, into: target, type: :route_handler,
+          evidence: "rails.route_to_controller", confidence: Confidence::HIGH,
+          location: location_for(path, line),
+          metadata: { "verb" => verb, "url" => url, "action" => action }
+        )
+      end
+
+      # "admin/users" -> "Admin::UsersController"
+      def controller_class_name(controller)
+        parts = controller.to_s.split("/").map { |part| camelize(part) }
+        "#{parts.join('::')}Controller"
+      end
+    end
+  end
+end