ripple_effect 0.1.0

data/lib/ripple_effect/extractors/base.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../node"
+require_relative "../edge"
+require_relative "../diagnostic"
+
+module RippleEffect
+  module Extractors
+    # Parses each project file at most once and hands out the Prism AST.
+    #
+    # The declaration index tells us *that* `belongs_to` was called; only the AST
+    # tells us what it was called with. Extractors share this cache so a file with
+    # associations, callbacks and delegations is still parsed a single time.
+    class SourceCache
+      def initialize(project:)
+        @project = project
+        @asts = {}
+        @diagnostics = []
+      end
+
+      # @return [Array<Diagnostic>] parse failures collected so far
+      attr_reader :diagnostics
+
+      # @param path [String] project-relative path
+      # @return [Prism::Node, nil] the program's root node, or nil when unparsable
+      def ast(path)
+        return @asts[path] if @asts.key?(path)
+
+        @asts[path] = parse(path)
+      end
+
+      private
+
+      def parse(path)
+        source = @project.read(path)
+        return nil if source.nil?
+
+        result = Prism.parse(source)
+
+        unless result.success?
+          @diagnostics << Diagnostic.new(
+            code: "unparsed_file",
+            severity: :warning,
+            path: path,
+            line: result.errors.first&.location&.start_line,
+            message: "could not parse #{path}: #{result.errors.first&.message}"
+          )
+          return nil
+        end
+
+        result.value
+      rescue ProjectError, SystemCallError, ArgumentError => e
+        @diagnostics << Diagnostic.new(
+          code: "unparsed_file",
+          severity: :warning,
+          path: path,
+          message: "could not read #{path}: #{e.message}"
+        )
+        nil
+      end
+    end
+
+    # Everything an extractor needs, passed as one object so adding a shared
+    # facility later does not change every extractor's signature.
+    Context = Struct.new(:project, :index, :graph, :sources, :diagnostics, keyword_init: true)
+
+    # Base class for all extractors.
+    #
+    # An extractor's only job is to add nodes and edges to the graph. It must never
+    # execute application code, and must never add an edge it cannot evidence.
+    #
+    # @abstract Subclasses implement {#extract}.
+    class Base
+      # @return [Context]
+      attr_reader :context
+
+      def initialize(context)
+        @context = context
+      end
+
+      # @return [void]
+      def extract = raise NotImplementedError
+
+      # @return [String] the config key that switches this extractor off, or nil
+      #   when the extractor is not optional
+      def self.feature = nil
+
+      private
+
+      def project = context.project
+      def index = context.index
+      def graph = context.graph
+      def sources = context.sources
+
+      def add_node(node) = graph.add_node(node)
+
+      # Adds an edge only when both endpoints exist, so a mistaken name can never
+      # create a dangling relationship.
+      #
+      # @return [Boolean] true when the edge was added
+      def add_edge(from:, into:, type:, evidence:, confidence:, location: nil, metadata: {})
+        return false if from.nil? || into.nil?
+
+        from_id = from.is_a?(Node) ? from.id : from
+        into_id = into.is_a?(Node) ? into.id : into
+        return false if from_id == into_id
+        return false unless graph.node?(from_id) && graph.node?(into_id)
+
+        graph.add_edge(
+          Edge.new(
+            from_id: from_id, into_id: into_id, type: type, evidence: evidence,
+            confidence: confidence, location: location, metadata: metadata
+          )
+        )
+      end
+
+      def add_diagnostic(code:, message:, path: nil, line: nil, severity: :warning)
+        context.diagnostics << Diagnostic.new(
+          code: code, message: message, path: path, line: line, severity: severity
+        )
+      end
+
+      # The single node for a qualified symbol name, or nil when the name is
+      # unknown or ambiguous. Ambiguity is not guessed away.
+      #
+      # @param name [String] e.g. "BillingService#charge"
+      # @return [Node, nil]
+      def node_for(name)
+        return nil if name.nil?
+
+        matches = graph.find_symbol(name)
+        matches.size == 1 ? matches.first : nil
+      end
+
+      # @return [Array<Node>] every node matching a qualified name
+      def nodes_for(name)
+        name.nil? ? [] : graph.find_symbol(name)
+      end
+
+      # @return [Node, nil] the file node for a project-relative path
+      def file_node_for(path)
+        graph.node("file:#{path}")
+      end
+
+      # Class and module declarations keyed by qualified name.
+      #
+      # Built once per extractor. Scanning the declaration list for each lookup
+      # turns ancestry walks into O(declarations) per class, which is quadratic on
+      # a large application.
+      #
+      # @return [Hash{String => StaticIndex::Declaration}]
+      def namespaces_by_name
+        @namespaces_by_name ||= index.declarations.select(&:namespace?).to_h do |declaration|
+          [declaration.qualified_name, declaration]
+        end
+      end
+
+      # Walks every node in the tree, depth first.
+      #
+      # @yieldparam node [Prism::Node]
+      def each_node(root, &block)
+        return unless root
+
+        stack = [root]
+        until stack.empty?
+          node = stack.pop
+          block.call(node)
+          node.compact_child_nodes.reverse_each { |child| stack << child }
+        end
+      end
+
+      # Walks call nodes paired with the innermost enclosing class/module path.
+      #
+      # @yieldparam call [Prism::CallNode]
+      # @yieldparam namespace [String, nil] e.g. "Commerce::Order"
+      def each_call_in_class(root, namespace: nil, &block)
+        return unless root
+
+        root.compact_child_nodes.each do |child|
+          case child
+          when Prism::ClassNode, Prism::ModuleNode
+            inner = join_namespace(namespace, constant_path_name(child.constant_path))
+            each_call_in_class(child.body, namespace: inner, &block)
+          when Prism::CallNode
+            block.call(child, namespace)
+            each_call_in_class(child, namespace: namespace, &block)
+          else
+            each_call_in_class(child, namespace: namespace, &block)
+          end
+        end
+      end
+
+      # @return [String, nil] "A::B" for a constant path node
+      def constant_path_name(node)
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode
+          parent = node.parent ? constant_path_name(node.parent) : nil
+          child = node.name&.to_s
+          return nil unless child
+
+          parent ? "#{parent}::#{child}" : child
+        end
+      end
+
+      def join_namespace(outer, inner)
+        return outer if inner.nil?
+
+        outer ? "#{outer}::#{inner}" : inner
+      end
+
+      # @return [String, nil] the literal value of a symbol or string argument
+      def literal_name(node)
+        case node
+        when Prism::SymbolNode, Prism::StringNode then node.unescaped
+        end
+      end
+
+      # Extracts literal keyword arguments from a call, ignoring anything dynamic.
+      #
+      # @return [Hash{String => Object}] only entries whose value is a literal
+      def literal_keywords(call)
+        arguments = call.arguments&.arguments || []
+        hash = arguments.last
+        return {} unless hash.is_a?(Prism::KeywordHashNode)
+
+        hash.elements.each_with_object({}) do |element, result|
+          next unless element.is_a?(Prism::AssocNode)
+
+          key = literal_name(element.key)
+          next unless key
+
+          value = literal_value(element.value)
+          result[key] = value unless value.nil?
+        end
+      end
+
+      def literal_value(node)
+        case node
+        when Prism::SymbolNode, Prism::StringNode then node.unescaped
+        when Prism::TrueNode then true
+        when Prism::FalseNode then false
+        when Prism::ArrayNode then node.elements.filter_map { |element| literal_value(element) }
+        end
+      end
+
+      # Positional arguments before any keyword hash.
+      #
+      # @return [Array<Prism::Node>]
+      def positional_arguments(call)
+        arguments = call.arguments&.arguments || []
+        arguments.grep_v(Prism::KeywordHashNode)
+      end
+
+      # @return [Array<String>] literal symbol/string positional arguments
+      def literal_positional_names(call)
+        positional_arguments(call).filter_map { |argument| literal_name(argument) }
+      end
+
+      # Rails' `Commerce::LineItem` <-> `:line_items` naming, applied only where
+      # Rails itself would apply it.
+      #
+      # @param name [String] e.g. "line_items"
+      # @return [String] e.g. "LineItem"
+      def classify(name)
+        singular = singularize(name.to_s)
+        singular.split("/").map { |part| camelize(part) }.join("::")
+      end
+
+      def camelize(name)
+        name.split("_").map { |part| part.empty? ? part : part[0].upcase + part[1..] }.join
+      end
+
+      # A small inflector. ActiveSupport is never loaded, and an unresolved target
+      # is reported rather than guessed at high confidence.
+      def singularize(name)
+        case name
+        when /(?:s|sh|ch|x|z)es\z/ then name.sub(/es\z/, "")
+        when /ies\z/ then name.sub(/ies\z/, "y")
+        when /s\z/ then name.end_with?("ss") ? name : name.sub(/s\z/, "")
+        else name
+        end
+      end
+
+      # @return [String] "path:line"
+      def location_for(path, line)
+        "#{path}:#{line}"
+      end
+    end
+  end
+end

data/lib/ripple_effect/extractors/rails_associations.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Extracts `belongs_to` / `has_one` / `has_many` / `has_and_belongs_to_many`
+    # relationships between models.
+    #
+    # Only literal forms are read. Scopes and blocks are never executed, and a
+    # polymorphic target has no static answer, so it is reported as a diagnostic
+    # rather than resolved to an invented constant.
+    class RailsAssociations < Base
+      MACROS = %w[belongs_to has_one has_many has_and_belongs_to_many].freeze
+
+      # `has_many :orders` implies a plural target; `belongs_to :account` a singular one.
+      PLURAL_MACROS = %w[has_many has_and_belongs_to_many].freeze
+
+      def self.feature = :associations
+
+      def extract
+        project.source_paths.each do |path|
+          next if project.test_path?(path)
+
+          each_call_in_class(sources.ast(path)) do |call, namespace|
+            next unless namespace
+            next unless MACROS.include?(call.name.to_s)
+            next unless call.receiver.nil?
+
+            extract_association(call, namespace, path)
+          end
+        end
+      end
+
+      private
+
+      def extract_association(call, namespace, path)
+        association_name = literal_positional_names(call).first
+        return if association_name.nil?
+
+        keywords = literal_keywords(call)
+        macro = call.name.to_s
+        line = call.location.start_line
+        model = node_for(namespace)
+        return if model.nil?
+
+        if keywords["polymorphic"] == true
+          add_diagnostic(
+            code: "unresolved_polymorphic_association",
+            path: path,
+            line: line,
+            message: "cannot statically resolve polymorphic #{macro} :#{association_name}"
+          )
+          return
+        end
+
+        target_name = keywords["class_name"] || conventional_class_name(association_name, macro)
+        target = node_for(target_name)
+
+        if target.nil?
+          add_diagnostic(
+            code: "unresolved_association_target",
+            severity: :info,
+            path: path,
+            line: line,
+            message: "#{macro} :#{association_name} points at #{target_name}, which is not indexed"
+          )
+          return
+        end
+
+        add_edge(
+          from: model,
+          into: target,
+          type: :association,
+          evidence: "rails.#{macro}",
+          # An explicit class_name is a fact; the conventional name is an inference,
+          # but one Rails itself makes, so it stays high once the target is indexed.
+          confidence: Confidence::HIGH,
+          location: location_for(path, line),
+          metadata: association_metadata(macro, association_name, keywords, target_name)
+        )
+      end
+
+      def association_metadata(macro, association_name, keywords, target_name)
+        {
+          "macro" => macro,
+          "association_name" => association_name,
+          "class_name" => target_name,
+          "foreign_key" => keywords["foreign_key"],
+          "through" => keywords["through"],
+          "polymorphic" => false
+        }.compact
+      end
+
+      def conventional_class_name(association_name, macro)
+        name = association_name.to_s
+        name = singularize(name) if PLURAL_MACROS.include?(macro)
+        classify(name)
+      end
+    end
+  end
+end

data/lib/ripple_effect/extractors/rails_callbacks.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Extracts ActiveRecord lifecycle callbacks.
+    #
+    # A callback is the classic invisible dependency: nothing in the source calls
+    # `send_receipt`, yet saving an Order runs it. Each callback becomes its own
+    # node so the reason for the impact survives into the explanation.
+    class RailsCallbacks < Base
+      MACROS = %w[
+        before_validation after_validation
+        before_save around_save after_save
+        before_create around_create after_create
+        before_update around_update after_update
+        before_destroy around_destroy after_destroy
+        after_commit after_rollback
+        after_touch after_initialize after_find
+      ].freeze
+
+      # Callbacks that accept a literal method name and may also carry conditions.
+      CONDITION_KEYS = %w[if unless].freeze
+
+      def self.feature = :callbacks
+
+      def extract
+        project.source_paths.each do |path|
+          next if project.test_path?(path)
+
+          each_call_in_class(sources.ast(path)) do |call, namespace|
+            next unless namespace
+            next unless MACROS.include?(call.name.to_s)
+            next unless call.receiver.nil?
+
+            extract_callback(call, namespace, path)
+          end
+        end
+      end
+
+      private
+
+      def extract_callback(call, namespace, path)
+        owner = node_for(namespace)
+        return if owner.nil?
+
+        macro = call.name.to_s
+        line = call.location.start_line
+        targets = literal_positional_names(call)
+
+        if targets.empty?
+          extract_block_callback(call, owner, macro, path, line) if call.block
+          return
+        end
+
+        keywords = literal_keywords(call)
+
+        targets.each do |target_name|
+          link_callback(owner: owner, macro: macro, target_name: target_name, path: path, line: line,
+                        keywords: keywords, namespace: namespace)
+        end
+      end
+
+      def link_callback(owner:, macro:, target_name:, path:, line:, keywords:, namespace:)
+        callback_node = add_node(
+          Node.new(
+            kind: :callback,
+            name: "#{namespace} #{macro} :#{target_name}",
+            qualified_name: "#{namespace}.#{macro}.#{target_name}",
+            path: path,
+            start_line: line,
+            end_line: line,
+            metadata: { "macro" => macro, "method" => target_name, "model" => namespace }.merge(
+              condition_metadata(keywords)
+            )
+          )
+        )
+
+        # The model owns its lifecycle, and the lifecycle invokes the method.
+        add_edge(
+          from: owner, into: callback_node, type: :callback,
+          evidence: "rails.#{macro}", confidence: Confidence::HIGH,
+          location: location_for(path, line)
+        )
+
+        add_edge(
+          from: callback_node, into: node_for("#{namespace}##{target_name}"),
+          type: :callback, evidence: "rails.#{macro}", confidence: Confidence::HIGH,
+          location: location_for(path, line), metadata: { "macro" => macro }
+        )
+
+        link_conditions(callback_node, keywords, namespace, path, line)
+      end
+
+      # `if: :publishable?` runs on every save too, so a change to the predicate
+      # is in the blast radius.
+      def link_conditions(callback_node, keywords, namespace, path, line)
+        CONDITION_KEYS.each do |key|
+          Array(keywords[key]).each do |condition|
+            next unless condition.is_a?(String)
+
+            add_edge(
+              from: callback_node, into: node_for("#{namespace}##{condition}"),
+              type: :callback, evidence: "rails.callback_condition",
+              confidence: Confidence::HIGH, location: location_for(path, line),
+              metadata: { "condition" => key, "method" => condition }
+            )
+          end
+        end
+      end
+
+      # An inline block has no method name to point at, but its body is ordinary
+      # code: the structure extractor already indexed the calls inside it, so we
+      # only need a node to anchor them to.
+      def extract_block_callback(call, owner, macro, path, line)
+        callback_node = add_node(
+          Node.new(
+            kind: :callback,
+            name: "#{owner.qualified_name} #{macro} (block)",
+            qualified_name: "#{owner.qualified_name}.#{macro}.block@#{line}",
+            path: path,
+            start_line: line,
+            end_line: call.block.location.end_line,
+            metadata: { "macro" => macro, "block" => true, "model" => owner.qualified_name }
+          )
+        )
+
+        add_edge(
+          from: owner, into: callback_node, type: :callback,
+          evidence: "rails.#{macro}", confidence: Confidence::HIGH,
+          location: location_for(path, line), metadata: { "block" => true }
+        )
+      end
+
+      def condition_metadata(keywords)
+        CONDITION_KEYS.each_with_object({}) do |key, result|
+          value = keywords[key]
+          result[key] = Array(value) if value
+        end
+      end
+    end
+  end
+end

data/lib/ripple_effect/extractors/rails_delegation.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RippleEffect
+  module Extractors
+    # Extracts ActiveSupport's `delegate :name, to: :user`.
+    #
+    # Delegation names a *receiver*, not a class. When that receiver is itself an
+    # association or a method we have already resolved, we can follow it; otherwise
+    # we record the delegation as a fact without pretending to know the target.
+    class RailsDelegation < Base
+      def self.feature = :delegation
+
+      def extract
+        project.source_paths.each do |path|
+          next if project.test_path?(path)
+
+          each_call_in_class(sources.ast(path)) do |call, namespace|
+            next unless namespace
+            next unless call.name.to_s == "delegate"
+            next unless call.receiver.nil?
+
+            extract_delegation(call, namespace, path)
+          end
+        end
+      end
+
+      private
+
+      def extract_delegation(call, namespace, path)
+        methods = literal_positional_names(call)
+        return if methods.empty?
+
+        keywords = literal_keywords(call)
+        target = keywords["to"]
+        return if target.nil?
+
+        owner = node_for(namespace)
+        return if owner.nil?
+
+        line = call.location.start_line
+        target_class = resolve_target_class(target, namespace)
+
+        methods.each do |method_name|
+          link_delegation(
+            owner: owner, method_name: method_name, target: target, target_class: target_class,
+            prefix: keywords["prefix"], namespace: namespace, path: path, line: line
+          )
+        end
+      end
+
+      def link_delegation(owner:, method_name:, target:, target_class:, prefix:, namespace:, path:, line:)
+        if target_class.nil?
+          add_diagnostic(
+            code: "unresolved_delegate_target",
+            severity: :info,
+            path: path,
+            line: line,
+            message: "delegate :#{method_name}, to: :#{target}: cannot resolve `#{target}`"
+          )
+          return
+        end
+
+        target_node = node_for("#{target_class}##{method_name}")
+
+        if target_node
+          add_edge(
+            from: owner, into: target_node, type: :delegate,
+            evidence: "rails.delegate", confidence: Confidence::MEDIUM,
+            location: location_for(path, line),
+            metadata: delegate_metadata(method_name, target, target_class, prefix, namespace)
+          )
+        else
+          # We resolved the receiver's class but it does not define the method --
+          # it may come from a superclass, a concern, or method_missing.
+          add_edge(
+            from: owner, into: node_for(target_class), type: :delegate,
+            evidence: "rails.delegate", confidence: Confidence::MEDIUM,
+            location: location_for(path, line),
+            metadata: delegate_metadata(method_name, target, target_class, prefix, namespace)
+          )
+        end
+      end
+
+      def delegate_metadata(method_name, target, target_class, prefix, namespace)
+        {
+          "method" => method_name,
+          "to" => target,
+          "target_class" => target_class,
+          "prefix" => prefix ? true : false,
+          "defined_on" => namespace
+        }
+      end
+
+      # A delegation target is a method name. The strongest static reading is an
+      # association of the same name on the same class, which the association
+      # extractor has already recorded.
+      def resolve_target_class(target, namespace)
+        return nil if target.to_s.start_with?("@") || target.to_s == "class"
+
+        association = association_target(namespace, target)
+        return association if association
+
+        candidate = classify(target.to_s)
+        node_for(candidate) ? candidate : nil
+      end
+
+      def association_target(namespace, target)
+        owner = node_for(namespace)
+        return nil unless owner
+
+        edge = graph.outgoing(owner.id).find do |candidate|
+          candidate.type == :association && candidate.metadata["association_name"] == target.to_s
+        end
+
+        edge && edge.metadata["class_name"]
+      end
+    end
+  end
+end