ripple_effect 0.1.0

data/lib/ripple_effect/extractors/rails_views.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Extracts dependencies from ERB templates.
+    #
+    # In a server-rendered Rails app the views are a large part of the dependency
+    # graph: helpers, models and partials are used mostly from templates. Skipping
+    # them understates the blast radius of every helper while still looking like a
+    # complete answer.
+    #
+    # The Ruby is lifted out of the ERB tags and parsed with Prism, so the same
+    # resolution and confidence rules apply as anywhere else. Templates are never
+    # rendered and never executed.
+    #
+    # Also handles `helper_method`, which is what makes a controller method
+    # callable from a template.
+    class RailsViews < Base
+      # Matches an ERB tag, capturing the Ruby inside it.
+      ERB_TAG = /<%(={1,2}|-|\#)?(.*?)(-)?%>/m
+
+      # `render` forms that name another template.
+      RENDER_METHODS = %w[render render_to_string].freeze
+
+      # Rails looks a template up by name; a partial is the same name with an
+      # underscore prefix.
+      TEMPLATE_EXTENSIONS = %w[.html.erb .erb .turbo_stream.erb .text.erb .js.erb].freeze
+
+      def self.feature = :views
+
+      def extract
+        # `helper_method` is a real relationship whether or not templates are
+        # indexed, so it is not gated on there being any views to find.
+        link_helper_methods
+
+        return if project.view_paths.empty?
+
+        build_view_nodes
+        link_controller_actions
+        project.view_paths.each { |path| extract_from_template(path) }
+      end
+
+      private
+
+      def build_view_nodes
+        project.view_paths.each do |path|
+          add_node(
+            Node.new(
+              kind: :view,
+              name: path,
+              qualified_name: path,
+              path: path,
+              metadata: { "partial" => partial?(path) }
+            )
+          )
+        end
+      end
+
+      # @return [Node, nil]
+      def view_node(path) = graph.node("view:#{path}:0:#{path}")
+
+      # A controller action renders its conventional template, so a change to the
+      # template is reachable from the action, and so from its route.
+      def link_controller_actions
+        index.declarations.each do |declaration|
+          next unless declaration.kind == :instance_method
+
+          owner = declaration.owner_name
+          next unless owner&.end_with?("Controller")
+
+          action = declaration.qualified_name.split("#").last
+          template = conventional_template(owner, action)
+          next unless template
+
+          add_edge(
+            from: node_for(declaration.qualified_name),
+            into: view_node(template),
+            type: :file_reference,
+            evidence: "rails.renders_template",
+            confidence: Confidence::HIGH,
+            location: template,
+            metadata: { "template" => template, "action" => action }
+          )
+        end
+      end
+
+      # `helper_method :current_company` is what makes a controller method
+      # reachable from a template. Without it, a change to that method looks
+      # confined to the controller when it is really used across the view layer.
+      def link_helper_methods
+        project.source_paths.each do |path|
+          next unless path.start_with?("app/controllers/")
+
+          each_call_in_class(sources.ast(path)) do |call, namespace|
+            next unless namespace
+            next unless call.name.to_s == "helper_method"
+            next unless call.receiver.nil?
+
+            literal_positional_names(call).each do |method_name|
+              link_exposed_method(namespace, method_name, path, call.location.start_line)
+            end
+          end
+        end
+      end
+
+      # The method is usually defined on the controller but often comes from an
+      # included concern, which is why `helper_method` is worth modelling. A
+      # definition on the controller is a fact; a uniquely named one elsewhere is
+      # the same inference made for any other call.
+      def link_exposed_method(namespace, method_name, path, line)
+        own = node_for("#{namespace}##{method_name}")
+        candidates = own ? [own] : methods_named(method_name)
+        return unless candidates.length == 1
+
+        add_edge(
+          from: node_for(namespace),
+          into: candidates.first,
+          type: :method_call,
+          evidence: "rails.helper_method",
+          confidence: own ? Confidence::HIGH : Confidence::MEDIUM,
+          location: location_for(path, line),
+          metadata: { "method" => method_name, "exposed_to" => "views" }
+        )
+      end
+
+      # "Admin::UsersController", "show" -> "app/views/admin/users/show.html.erb"
+      def conventional_template(controller, action)
+        directory = controller.delete_suffix("Controller")
+                              .split("::")
+                              .map { |part| underscore(part) }
+                              .join("/")
+
+        find_template("#{directory}/#{action}")
+      end
+
+      # @param stem [String] e.g. "orders/show" or "shared/_menu"
+      # @return [String, nil] the matching indexed template path
+      def find_template(stem)
+        TEMPLATE_EXTENSIONS.each do |extension|
+          candidate = "app/views/#{stem}#{extension}"
+          return candidate if view_index.include?(candidate)
+        end
+
+        nil
+      end
+
+      def view_index
+        @view_index ||= project.view_paths.to_h { |path| [path, true] }
+      end
+
+      def extract_from_template(path)
+        source = compile(path)
+        return unless source
+
+        result = Prism.parse(source)
+        unless result.success?
+          add_diagnostic(
+            code: "unparsed_file",
+            severity: :info,
+            path: path,
+            message: "could not parse the Ruby compiled from #{path}"
+          )
+          return
+        end
+
+        from = view_node(path)
+        return unless from
+
+        each_node(result.value) do |node|
+          case node
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            link_constant(from, node, path)
+          when Prism::CallNode
+            link_call(from, node, path)
+          end
+        end
+      end
+
+      # Extracts the Ruby from a template as a plain sequence of statements.
+      #
+      # ERB's own compiler is not usable here. Rails templates rely on
+      # ActionView's handler, which understands `<%= form_with do |f| %>`;
+      # stdlib ERB compiles that to `_erbout << (form_with do |f|).to_s`, which
+      # is a syntax error. Emitting each tag's code as a bare statement keeps
+      # block forms and `<% end %>` balanced, and is all we need: we are looking
+      # for constants, calls and renders, not rendering anything.
+      def compile(path)
+        source = project.read(path)
+        return nil if source.nil?
+
+        statements = source.scan(ERB_TAG).filter_map do |marker, code, _trailing|
+          next if marker == "#" # `<%# a comment %>`
+
+          code.to_s.strip.delete_suffix("-")
+        end
+
+        statements.reject(&:empty?).join("\n")
+      rescue ProjectError => e
+        add_diagnostic(code: "unparsed_file", severity: :info, path: path,
+                       message: "could not read #{path}: #{e.message}")
+        nil
+      end
+
+      def link_constant(from, node, path)
+        name = constant_path_name(node)
+        return unless name
+
+        add_edge(
+          from: from,
+          into: node_for(name),
+          type: :constant_reference,
+          evidence: "view.constant_reference",
+          confidence: Confidence::HIGH,
+          location: path,
+          metadata: { "constant" => name }
+        )
+      end
+
+      def link_call(from, node, path)
+        name = node.name.to_s
+        return link_render(from, node, path) if RENDER_METHODS.include?(name) && node.receiver.nil?
+
+        # An explicit receiver in a template is usually a local or instance
+        # variable of unknown type. Only bare calls (helpers and model-backed
+        # methods) are resolvable here.
+        return unless node.receiver.nil?
+
+        link_helper_call(from, name, path)
+      end
+
+      # Same policy as everywhere else: a unique name is a medium-confidence
+      # inference, an ambiguous one is worth nothing.
+      def link_helper_call(from, name, path)
+        candidates = methods_named(name)
+        return unless candidates.length == 1
+
+        add_edge(
+          from: from,
+          into: candidates.first,
+          type: :method_call,
+          evidence: "view.helper_call",
+          confidence: Confidence::MEDIUM,
+          location: path,
+          metadata: { "method" => name }
+        )
+      end
+
+      # `render "shared/menu"`, `render partial: "shared/menu"`.
+      def link_render(from, call, path)
+        target = literal_positional_names(call).first || literal_keywords(call)["partial"]
+        return unless target
+
+        template = resolve_partial(target, path)
+        return unless template
+
+        add_edge(
+          from: from,
+          into: view_node(template),
+          type: :file_reference,
+          evidence: "rails.render_partial",
+          confidence: Confidence::HIGH,
+          location: path,
+          metadata: { "partial" => target }
+        )
+      end
+
+      # A bare name resolves relative to the rendering template's own directory;
+      # a name with a slash is relative to app/views.
+      def resolve_partial(target, path)
+        # A dynamic partial name cannot be resolved statically.
+        return nil if target.include?("\#{")
+
+        if target.include?("/")
+          directory, base = target.split("/").then { |parts| [parts[0..-2].join("/"), parts.last] }
+          find_template("#{directory}/_#{base}")
+        else
+          directory = File.dirname(path).delete_prefix("app/views/")
+          find_template("#{directory}/_#{target}")
+        end
+      end
+
+      def methods_named(name)
+        @methods_by_name ||= graph.nodes.select(&:method?).group_by do |node|
+          node.qualified_name.to_s.split(/[#.]/).last
+        end
+
+        @methods_by_name.fetch(name, [])
+      end
+
+      def partial?(path) = File.basename(path).start_with?("_")
+
+      def underscore(name)
+        name.gsub(/([a-z\d])([A-Z])/, '\1_\2').gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').downcase
+      end
+    end
+  end
+end

data/lib/ripple_effect/extractors/ruby_structure.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Turns the language-level index into graph nodes and edges: files, classes,
+    # modules, methods, inheritance, mixins, constant references and method calls.
+    #
+    # Every other extractor builds on the nodes this one creates, so it always runs
+    # first and is never optional.
+    class RubyStructure < Base
+      def extract
+        build_file_nodes
+        build_declaration_nodes
+        build_containment_edges
+        build_inheritance_and_mixin_edges
+        build_constant_reference_edges
+        build_method_call_edges
+      end
+
+      private
+
+      def build_file_nodes
+        project.source_paths.each do |path|
+          add_node(
+            Node.new(
+              kind: project.test_path?(path) ? :test_file : :file,
+              name: path,
+              path: path,
+              qualified_name: path
+            )
+          )
+        end
+      end
+
+      def build_declaration_nodes
+        index.declarations.each do |declaration|
+          add_node(
+            Node.new(
+              kind: declaration.kind,
+              name: declaration.qualified_name,
+              qualified_name: declaration.qualified_name,
+              path: declaration.path,
+              start_line: declaration.start_line,
+              end_line: declaration.end_line,
+              metadata: { "owner" => declaration.owner_name }.compact
+            )
+          )
+        end
+      end
+
+      # A file depends on what it declares: changing a class should reach the file
+      # node, and a test file's convention edges hang off the same structure.
+      def build_containment_edges
+        index.declarations.each do |declaration|
+          node = declaration_node(declaration)
+          next unless node
+
+          add_edge(
+            from: file_node_for(declaration.path),
+            into: node,
+            type: :file_reference,
+            evidence: "ruby.file_declares",
+            confidence: Confidence::HIGH,
+            location: node.location
+          )
+
+          next unless declaration.method? && declaration.owner_name
+
+          # The owning class depends on its methods: a change to `Order#total`
+          # is reachable from anything that reaches `Order`.
+          add_edge(
+            from: node_for(declaration.owner_name),
+            into: node,
+            type: :file_reference,
+            evidence: "ruby.defines_method",
+            confidence: Confidence::HIGH,
+            location: node.location
+          )
+        end
+      end
+
+      def build_inheritance_and_mixin_edges
+        index.declarations.select(&:namespace?).each do |declaration|
+          node = declaration_node(declaration)
+          next unless node
+
+          if declaration.superclass_name
+            add_edge(
+              from: node,
+              into: node_for(declaration.superclass_name),
+              type: :inheritance,
+              evidence: "ruby.superclass",
+              confidence: Confidence::HIGH,
+              location: node.location,
+              metadata: { "superclass" => declaration.superclass_name }
+            )
+          end
+
+          declaration.mixins.each do |mixin|
+            add_edge(
+              from: node,
+              into: node_for(mixin[:target]),
+              type: mixin[:type],
+              evidence: "ruby.#{mixin[:type]}",
+              confidence: Confidence::HIGH,
+              location: node.location,
+              metadata: { "module" => mixin[:target] }
+            )
+          end
+        end
+      end
+
+      def build_constant_reference_edges
+        index.constant_references.each do |reference|
+          next unless reference.resolved?
+
+          from = reference.enclosing_name ? node_for(reference.enclosing_name) : file_node_for(reference.path)
+          next unless from
+
+          add_edge(
+            from: from,
+            into: node_for(reference.target_name),
+            type: :constant_reference,
+            evidence: "rubydex.constant_reference",
+            confidence: Confidence::HIGH,
+            location: location_for(reference.path, reference.line),
+            metadata: { "constant" => reference.name }
+          )
+        end
+      end
+
+      # Call sites come in two flavours. When the indexer resolved the receiver we
+      # know exactly which method is meant. When it did not, we look the bare method
+      # name up in the index: a unique match is worth a medium-confidence edge, an
+      # ambiguous or unknown one is worth a diagnostic and nothing else.
+      def build_method_call_edges
+        index.method_references.each do |reference|
+          from = caller_node(reference)
+          next unless from
+
+          if reference.resolved_receiver?
+            link_resolved_call(reference, from)
+          else
+            link_inferred_call(reference, from)
+          end
+        end
+      end
+
+      def caller_node(reference)
+        if reference.enclosing_name
+          node_for(reference.enclosing_name) || file_node_for(reference.path)
+        else
+          file_node_for(reference.path)
+        end
+      end
+
+      def link_resolved_call(reference, from)
+        target = node_for("#{reference.receiver_name}##{reference.name}") ||
+                 node_for("#{reference.receiver_name}.#{reference.name}")
+
+        return link_inferred_call(reference, from) if target.nil?
+
+        add_edge(
+          from: from,
+          into: target,
+          type: :method_call,
+          evidence: "rubydex.method_reference",
+          confidence: Confidence::HIGH,
+          location: location_for(reference.path, reference.line),
+          metadata: { "method" => reference.name, "receiver" => reference.receiver_name }
+        )
+      end
+
+      def link_inferred_call(reference, from)
+        candidates = methods_named(reference.name)
+
+        case candidates.size
+        when 0
+          nil
+        when 1
+          add_edge(
+            from: from,
+            into: candidates.first,
+            type: :method_call,
+            evidence: "inference.unique_method_name",
+            confidence: Confidence::MEDIUM,
+            location: location_for(reference.path, reference.line),
+            metadata: { "method" => reference.name }
+          )
+        else
+          # Several methods share this name and we cannot tell which is meant.
+          # Guessing here is exactly the kind of confident falsehood that would
+          # cost the user their trust, so we record the ambiguity instead.
+          add_diagnostic(
+            code: "unresolved_method_receiver",
+            severity: :info,
+            path: reference.path,
+            line: reference.line,
+            message: "cannot resolve receiver for `#{reference.name}`; " \
+                     "#{candidates.size} methods share that name"
+          )
+        end
+      end
+
+      # Index of bare method name -> method nodes, built once.
+      def methods_named(name)
+        @methods_by_name ||= graph.nodes.select(&:method?).group_by do |node|
+          node.qualified_name.to_s.split(/[#.]/).last
+        end
+
+        @methods_by_name.fetch(name, [])
+      end
+
+      def declaration_node(declaration)
+        graph.find_symbol(declaration.qualified_name).find { |node| node.path == declaration.path }
+      end
+    end
+  end
+end

data/lib/ripple_effect/extractors/test_conventions.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Links test files to the code they cover.
+    #
+    # Two kinds of evidence, ranked differently. A test that references
+    # `BillingService` is strong evidence; one that merely sits at the
+    # conventional path is weaker. The structure extractor usually produces the
+    # strong edge already, so the convention edge is a safety net for tests that
+    # exercise code indirectly.
+    class TestConventions < Base
+      # app/services/billing_service.rb -> spec/services/billing_service_spec.rb
+      RSPEC_SUFFIX = "_spec.rb"
+      MINITEST_SUFFIX = "_test.rb"
+
+      # Controllers are also commonly covered by request specs named after the
+      # resource rather than the class, which is a weaker match.
+      REQUEST_SPEC_DIRECTORIES = %w[spec/requests spec/controllers test/controllers test/integration].freeze
+
+      def extract
+        project.test_paths.each do |test_path|
+          test_node = file_node_for(test_path)
+          next unless test_node
+
+          link_conventional_target(test_path, test_node)
+        end
+
+        link_request_specs
+      end
+
+      private
+
+      # spec/models/user_spec.rb -> app/models/user.rb
+      def link_conventional_target(test_path, test_node)
+        source_path = conventional_source_path(test_path)
+        return if source_path.nil?
+
+        source_node = file_node_for(source_path)
+        return if source_node.nil?
+
+        add_edge(
+          from: test_node, into: source_node,
+          type: :test_convention,
+          evidence: evidence_for(test_path),
+          confidence: Confidence::HIGH,
+          location: test_path,
+          metadata: { "source" => source_path }
+        )
+
+        # Reach the declarations in that file too, so inspecting a single method
+        # still surfaces the file's spec.
+        graph.nodes_by_path(source_path).each do |node|
+          next if node.kind == :file
+
+          add_edge(
+            from: test_node, into: node,
+            type: :test_convention,
+            evidence: evidence_for(test_path),
+            confidence: Confidence::MEDIUM,
+            location: test_path,
+            metadata: { "source" => source_path }
+          )
+        end
+      end
+
+      def evidence_for(test_path)
+        test_path.end_with?(MINITEST_SUFFIX) ? "convention.minitest_path" : "convention.rspec_path"
+      end
+
+      def conventional_source_path(test_path)
+        stem = strip_suffix(test_path)
+        return nil if stem.nil?
+
+        relative = stem.split("/", 2).last
+        return nil if relative.nil?
+
+        candidates(relative).find { |candidate| project.indexed?(candidate) }
+      end
+
+      def strip_suffix(test_path)
+        return test_path.delete_suffix(RSPEC_SUFFIX) if test_path.end_with?(RSPEC_SUFFIX)
+        return test_path.delete_suffix(MINITEST_SUFFIX) if test_path.end_with?(MINITEST_SUFFIX)
+
+        nil
+      end
+
+      # `spec/models/user` -> app/models/user.rb, then lib/models/user.rb, then
+      # the same name anywhere under app/.
+      def candidates(relative)
+        ["app/#{relative}.rb", "lib/#{relative}.rb", "#{relative}.rb"]
+      end
+
+      # `spec/requests/orders_spec.rb` conventionally covers `OrdersController`,
+      # but the naming is looser, so this stays a low-confidence hint.
+      def link_request_specs
+        project.test_paths.each do |test_path|
+          next unless REQUEST_SPEC_DIRECTORIES.any? { |dir| test_path.start_with?("#{dir}/") }
+
+          test_node = file_node_for(test_path)
+          next unless test_node
+
+          controller = request_spec_controller(test_path)
+          next unless controller
+
+          add_edge(
+            from: test_node, into: node_for(controller),
+            type: :test_convention,
+            evidence: "convention.request_spec_path",
+            confidence: Confidence::LOW,
+            location: test_path,
+            metadata: { "controller" => controller }
+          )
+        end
+      end
+
+      def request_spec_controller(test_path)
+        stem = strip_suffix(test_path)
+        return nil if stem.nil?
+
+        base = stem.split("/").last
+        return nil if base.nil?
+
+        name = base.end_with?("_controller") ? base.delete_suffix("_controller") : base
+        namespace = stem.split("/")[2..-2] || []
+        parts = (namespace + ["#{name}_controller"]).map { |part| camelize(part) }
+        candidate = parts.join("::")
+
+        node_for(candidate) ? candidate : nil
+      end
+    end
+  end
+end