ripple_effect 0.1.0

data/lib/ripple_effect/static_index/rubydex_adapter.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require_relative "adapter"
+require_relative "../diagnostic"
+require_relative "../error"
+
+module RippleEffect
+  module StaticIndex
+    # Rubydex-backed implementation of {Adapter}.
+    #
+    # Rubydex names singleton methods `Order::<Order>#recent` and suffixes every
+    # method with `()`; we normalise to the documented canonical forms `Order.recent`
+    # and `Order#save` here, so no other part of the codebase has to know that.
+    #
+    # Rubydex also reports a call site's receiver only when it could resolve it.
+    # We never invent one: an unresolved receiver becomes a lower-confidence,
+    # name-based candidate in {Extractors::RubyStructure}, or a diagnostic.
+    class RubydexAdapter < Adapter
+      # Rubydex synthesises this document for Ruby's core classes. Those are not
+      # part of the analysed project, so we drop everything it contains.
+      BUILT_IN_URI = "rubydex:built-in"
+
+      # Rubydex models each mixin form as its own class.
+      MIXIN_TYPES = {
+        "Rubydex::Include" => :include,
+        "Rubydex::Prepend" => :prepend,
+        "Rubydex::Extend" => :extend
+      }.freeze
+
+      # Rubydex rules meaning the source could not be read. Everything else it
+      # reports is a lint finding about code it parsed fine.
+      FATAL_RULES = %w[SyntaxError ParseError].freeze
+
+      # Rubydex reports zero-indexed lines. Git hunks, editors and our own output
+      # all count from one.
+      LINE_OFFSET = 1
+
+      attr_reader :diagnostics, :declarations, :method_references, :constant_references
+
+      # @param project [Project] used to make paths project-relative and to keep
+      #   the index inside the project root
+      def initialize(project:)
+        super()
+        @project = project
+        @declarations = []
+        @method_references = []
+        @constant_references = []
+        @diagnostics = []
+        @by_path = Hash.new { |hash, key| hash[key] = [] }
+        @indexed = false
+      end
+
+      # @return [String] e.g. "rubydex 0.4.1"
+      def self.backend_version
+        require "rubydex"
+        "rubydex #{Rubydex::VERSION}"
+      rescue LoadError
+        "rubydex (not installed)"
+      end
+
+      def backend_version = self.class.backend_version
+
+      # Indexes +paths+ and normalises everything Rubydex returns.
+      #
+      # A failure inside a single file is recorded as a diagnostic; only a failure
+      # to build the index at all raises.
+      #
+      # @param paths [Array<String>] absolute paths
+      # @return [self]
+      # @raise [IndexError] when Rubydex is unavailable or the index cannot be built
+      def index(paths:)
+        graph = build_graph(paths)
+        collect_declarations(graph)
+        collect_method_references(graph)
+        collect_constant_references(graph)
+        collect_rubydex_diagnostics(graph)
+        @indexed = true
+        self
+      end
+
+      # @return [Boolean]
+      def indexed? = @indexed
+
+      # @return [Array<Declaration>] declarations in +path+, outermost first
+      def declarations_in(path:)
+        @by_path[path]
+      end
+
+      # The innermost declaration whose line range covers +line+.
+      #
+      # Methods are preferred over the classes that contain them, which is what
+      # makes a one-line diff hunk resolve to a method rather than to its class.
+      #
+      # @return [Declaration, nil]
+      def declaration_at(path:, line:)
+        covering = @by_path[path].select do |declaration|
+          next false unless declaration.start_line
+
+          line.between?(declaration.start_line, declaration.end_line || declaration.start_line)
+        end
+
+        covering.min_by do |declaration|
+          [(declaration.end_line || declaration.start_line) - declaration.start_line, declaration.method? ? 0 : 1]
+        end
+      end
+
+      private
+
+      def build_graph(paths)
+        require "rubydex"
+
+        graph = Rubydex::Graph.new
+        graph.index_all(Array(paths))
+        graph.resolve
+        graph
+      rescue LoadError => e
+        raise IndexError, "rubydex could not be loaded: #{e.message}"
+      rescue StandardError => e
+        raise IndexError, "rubydex failed to index the project: #{e.class}: #{e.message}"
+      end
+
+      # Rubydex's resolved view gives us fully-qualified entities; each carries its
+      # concrete definition sites, which is where locations and mixins live.
+      def collect_declarations(graph)
+        graph.declarations.each do |entity|
+          kind = declaration_kind(entity)
+          next unless kind
+
+          definitions = safe(entity, :definitions) || []
+          definitions.each do |definition|
+            path = relative_uri(definition)
+            next unless path
+
+            declaration = build_declaration(entity, definition, kind, path)
+            @declarations << declaration
+            @by_path[path] << declaration
+          end
+        end
+
+        @declarations.sort_by! { |d| [d.path, d.start_line || 0, d.qualified_name] }
+        @by_path.each_value { |list| list.sort_by! { |d| [d.start_line || 0, d.qualified_name] } }
+      end
+
+      def build_declaration(entity, definition, kind, path)
+        location = definition.location
+
+        Declaration.new(
+          kind: kind,
+          qualified_name: canonical_name(entity.name, kind),
+          name: display_name(entity.name, kind),
+          path: path,
+          start_line: one_indexed(location.start_line),
+          end_line: one_indexed(location.end_line),
+          owner_name: canonical_owner(entity),
+          superclass_name: superclass_name(definition),
+          mixins: mixins_for(definition)
+        )
+      end
+
+      def declaration_kind(entity)
+        case entity
+        when defined?(Rubydex::Method) ? Rubydex::Method : nil
+          singleton_owner?(entity) ? :class_method : :instance_method
+        when defined?(Rubydex::Class) ? Rubydex::Class : nil
+          :class
+        when defined?(Rubydex::Module) ? Rubydex::Module : nil
+          :module
+        end
+      end
+
+      # A singleton method is one whose owner is Rubydex's `Foo::<Foo>` shadow class.
+      def singleton_owner?(entity)
+        owner = safe(entity, :owner)
+        owner ? owner.name.to_s.include?("::<") : false
+      end
+
+      # "Commerce::Order::<Order>#recent()" -> "Commerce::Order.recent"
+      # "Commerce::Order#capture_payment()" -> "Commerce::Order#capture_payment"
+      def canonical_name(raw, kind)
+        name = raw.to_s.delete_suffix("()")
+
+        case kind
+        when :class_method
+          namespace, method = name.split("#", 2)
+          "#{namespace.to_s.sub(/::<[^>]+>\z/, '')}.#{method}"
+        else
+          name
+        end
+      end
+
+      def display_name(raw, kind) = canonical_name(raw, kind)
+
+      def canonical_owner(entity)
+        owner = safe(entity, :owner)
+        return nil unless owner
+
+        name = owner.name.to_s.sub(/::<[^>]+>\z/, "")
+        name == "Object" ? nil : name
+      end
+
+      def superclass_name(definition)
+        reference = safe(definition, :superclass)
+        return nil unless reference
+
+        resolved_target(reference)
+      end
+
+      def mixins_for(definition)
+        (safe(definition, :mixins) || []).filter_map do |mixin|
+          type = mixin_type(mixin)
+          next unless type
+
+          reference = safe(mixin, :constant_reference)
+          target = reference && (resolved_target(reference) || safe(reference, :name))
+          next unless target
+
+          { type: type, target: target.to_s }
+        end
+      end
+
+      def mixin_type(mixin)
+        MIXIN_TYPES[mixin.class.name]
+      end
+
+      def collect_method_references(graph)
+        graph.method_references.each do |reference|
+          path = relative_uri(reference)
+          next unless path
+
+          line = one_indexed(reference.location.start_line)
+
+          @method_references << MethodReference.new(
+            name: reference.name.to_s,
+            receiver_name: receiver_name(reference),
+            path: path,
+            line: line,
+            enclosing_name: enclosing_name(path, line)
+          )
+        end
+
+        @method_references.sort_by! { |r| [r.path, r.line, r.name] }
+      end
+
+      # Rubydex populates the receiver only when it resolved it, so a nil here is
+      # information, not a gap to paper over.
+      def receiver_name(reference)
+        receiver = safe(reference, :receiver)
+        return nil unless receiver
+
+        name = safe(receiver, :name)
+        return nil unless name
+
+        name.to_s.sub(/::<[^>]+>\z/, "")
+      end
+
+      def collect_constant_references(graph)
+        graph.constant_references.each do |reference|
+          path = relative_uri(reference)
+          next unless path
+
+          name = safe(reference, :name) || safe(safe(reference, :declaration), :name)
+          next unless name
+          # Rubydex emits a synthetic `<Foo>` reference for each singleton class body.
+          next if name.to_s.start_with?("<")
+
+          line = one_indexed(reference.location.start_line)
+
+          @constant_references << ConstantReference.new(
+            name: name.to_s,
+            target_name: resolved_target(reference),
+            path: path,
+            line: line,
+            enclosing_name: enclosing_name(path, line)
+          )
+        end
+
+        @constant_references.sort_by! { |r| [r.path, r.line, r.name] }
+      end
+
+      def resolved_target(reference)
+        declaration = safe(reference, :declaration)
+        return nil unless declaration
+
+        name = safe(declaration, :name)
+        name&.to_s&.delete_suffix("()")
+      end
+
+      # Most Rubydex diagnostics are lint findings ("assigned but unused
+      # variable", "Dynamic mixin argument") against files it parsed fine.
+      # Reporting those as parse failures would be wrong and would drown the
+      # diagnostics that actually limit the analysis, so they are recorded as
+      # informational notes. Only a rule meaning the source could not be read
+      # counts as a parse failure.
+      def collect_rubydex_diagnostics(graph)
+        (safe(graph, :diagnostics) || []).each do |diagnostic|
+          path = relative_uri(diagnostic)
+          next unless path
+
+          rule = rule_name(diagnostic)
+          fatal = FATAL_RULES.include?(rule)
+
+          @diagnostics << Diagnostic.new(
+            code: fatal ? "unparsed_file" : "index_note",
+            severity: fatal ? :warning : :info,
+            path: path,
+            line: one_indexed(safe(safe(diagnostic, :location), :start_line)),
+            message: [rule, safe(diagnostic, :message).to_s].compact.join(": ")
+          )
+        end
+      end
+
+      # @return [String, nil] e.g. "ParseWarning"
+      def rule_name(diagnostic)
+        rule = safe(diagnostic, :rule)
+        name = rule && safe(rule, :name)
+        return nil unless name
+
+        name.to_s.split("::").last
+      end
+
+      # The declaration enclosing a reference, so we know who is doing the calling.
+      def enclosing_name(path, line)
+        declaration_at(path: path, line: line)&.qualified_name
+      end
+
+      # @return [String, nil] project-relative path, or nil for built-ins and
+      #   anything outside the project root
+      def relative_uri(object)
+        location = safe(object, :location)
+        uri = location && safe(location, :uri)
+        return nil if uri.nil? || uri.to_s == BUILT_IN_URI
+
+        absolute = uri.to_s.delete_prefix("file://")
+        return nil unless @project.inside_root?(absolute)
+
+        relative = @project.relative_path(absolute)
+        relative.start_with?("/") ? nil : relative
+      end
+
+      # @return [Integer, nil] +line+ shifted into one-indexed space
+      def one_indexed(line)
+        line.nil? ? nil : line + LINE_OFFSET
+      end
+
+      # Rubydex's surface is still moving; a missing accessor should degrade the
+      # analysis, not crash it.
+      def safe(object, method)
+        return nil unless object.respond_to?(method)
+
+        object.public_send(method)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/ripple_effect/traversal/impact_walker.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "../confidence"
+
+module RippleEffect
+  module Traversal
+    # One impacted node, together with the reason it is impacted.
+    #
+    # The evidence path is the product: it is what lets a developer check our
+    # answer instead of trusting it.
+    class Impact
+      attr_reader :node, :depth, :confidence, :evidence_path, :source_id
+
+      # @param node [Node] the impacted node
+      # @param depth [Integer] hops from the changed node
+      # @param evidence_path [Array<Edge>] edges from the changed node outward
+      # @param source_id [String] the changed node this impact originated from
+      def initialize(node:, depth:, evidence_path:, source_id:)
+        @node = node
+        @depth = depth
+        @evidence_path = evidence_path.freeze
+        @source_id = source_id
+        @confidence = Confidence.weakest(evidence_path.map(&:confidence))
+        freeze
+      end
+
+      # @return [Edge, nil] the edge that reaches this node
+      def reason = evidence_path.last
+
+      # @return [Hash] JSON-compatible representation
+      def to_h
+        node.to_h.merge(
+          "depth" => depth,
+          "confidence" => confidence.to_s,
+          "source_id" => source_id,
+          "evidence_path" => evidence_path.map do |edge|
+            {
+              "type" => edge.type.to_s,
+              "evidence" => edge.evidence,
+              "confidence" => edge.confidence.to_s,
+              "location" => edge.location
+            }
+          end
+        )
+      end
+    end
+
+    # Breadth-first reverse traversal from a set of changed nodes.
+    #
+    # Breadth-first, so the reported path is the shortest chain of reasoning and
+    # therefore the quickest to verify by hand. Where two paths are equally short,
+    # the more confident one wins.
+    class ImpactWalker
+      # @param graph [Graph]
+      # @param min_confidence [Symbol] edges weaker than this are not traversed
+      # @param edge_types [Array<Symbol>, nil] restrict traversal to these types
+      # @param exclude_edge_types [Array<Symbol>] never traverse these types
+      def initialize(graph:, min_confidence: Confidence::MEDIUM, edge_types: nil, exclude_edge_types: [])
+        @graph = graph
+        @min_confidence = Confidence.cast(min_confidence)
+        @edge_types = edge_types&.map { |type| Edge.cast_type(type) }
+        @exclude_edge_types = exclude_edge_types.map { |type| Edge.cast_type(type) }
+      end
+
+      # Walks outward from every node in +from_ids+.
+      #
+      # @param from_ids [Array<String>]
+      # @param depth [Integer, nil] maximum hops, nil for unlimited
+      # @param direction [Symbol] :dependents (reverse) or :dependencies (forward)
+      # @return [Array<Impact>] sorted by depth, then node ID
+      def walk(from_ids, depth: nil, direction: :dependents)
+        best = {}
+        starts = Array(from_ids).select { |id| @graph.node?(id) }.sort
+        # Never report a changed node as impacted by itself.
+        seeds = starts.to_h { |id| [id, true] }
+
+        starts.each do |start_id|
+          traverse(start_id, depth, direction, seeds, best)
+        end
+
+        best.values.sort_by { |impact| [impact.depth, impact.node.id] }
+      end
+
+      private
+
+      def traverse(start_id, max_depth, direction, seeds, best)
+        # Queue entries are [node_id, evidence path so far].
+        queue = [[start_id, []]]
+        visited = { start_id => 0 }
+
+        until queue.empty?
+          current_id, path = queue.shift
+          current_depth = path.length
+          next if max_depth && current_depth >= max_depth
+
+          edges_from(current_id, direction).each do |edge|
+            next unless traversable?(edge)
+
+            neighbour_id = direction == :dependents ? edge.from_id : edge.into_id
+            next_depth = current_depth + 1
+
+            node = @graph.node(neighbour_id)
+            next unless node
+
+            existing = visited[neighbour_id]
+            # A strictly longer route tells us nothing we do not already know.
+            next if existing && existing < next_depth
+
+            next_path = path + [edge]
+
+            # Only continue outward the first time we reach a node at this depth;
+            # an equally short alternative still goes to #record, which decides
+            # between two same-length explanations on confidence.
+            if existing.nil?
+              visited[neighbour_id] = next_depth
+              queue << [neighbour_id, next_path]
+            end
+
+            next if seeds[neighbour_id]
+
+            record(best, node, next_depth, next_path, start_id)
+          end
+        end
+      end
+
+      # Keeps the shortest path, breaking ties on confidence: of two equally short
+      # explanations, we show the one we are surest of.
+      def record(best, node, depth, path, source_id)
+        impact = Impact.new(node: node, depth: depth, evidence_path: path, source_id: source_id)
+        current = best[node.id]
+
+        return best[node.id] = impact if current.nil?
+        return if current.depth < depth
+        return best[node.id] = impact if depth < current.depth
+
+        best[node.id] = impact if Confidence.rank(impact.confidence) > Confidence.rank(current.confidence)
+      end
+
+      def edges_from(id, direction)
+        edges = direction == :dependents ? @graph.incoming(id) : @graph.outgoing(id)
+        edges.sort_by { |edge| [edge.from_id, edge.into_id, edge.type.to_s] }
+      end
+
+      def traversable?(edge)
+        return false unless Confidence.at_least?(edge.confidence, @min_confidence)
+        return false if @exclude_edge_types.include?(edge.type)
+        return false if @edge_types && !@edge_types.include?(edge.type)
+
+        true
+      end
+    end
+  end
+end

data/lib/ripple_effect/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  VERSION = "0.1.0"
+
+  # Bumped whenever the machine-readable result envelope changes shape.
+  SCHEMA_VERSION = 1
+
+  # Bumped whenever the on-disk cache layout changes.
+  CACHE_SCHEMA_VERSION = 1
+end

data/lib/ripple_effect.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "ripple_effect/version"
+require_relative "ripple_effect/error"
+require_relative "ripple_effect/confidence"
+require_relative "ripple_effect/node"
+require_relative "ripple_effect/edge"
+require_relative "ripple_effect/diagnostic"
+require_relative "ripple_effect/graph"
+
+# Ripple Effect maps the blast radius of Ruby on Rails changes.
+#
+# It combines Ruby-aware static indexing with Rails semantics (callbacks,
+# associations, routes, jobs, mailers, concerns and test references) to explain
+# what may be affected before you refactor.
+#
+# The analysis is deterministic and local. Ripple Effect never boots the target
+# application, evaluates its source, connects to a database, or makes a network call.
+#
+# @example Inspect one symbol
+#   result = RippleEffect.analyze("BillingService#charge")
+#   result.impacted_nodes.map(&:name)
+#
+# @example Analyse a Git range
+#   result = RippleEffect.diff("main")
+#   result.risk.level # => :high
+module RippleEffect
+  class << self
+    # Analyses the blast radius of a single symbol.
+    #
+    # @param symbol [String] e.g. "BillingService#charge", "User", "User.find"
+    # @param root [String] project root
+    # @param options [Hash] forwarded to {Analyzer#inspect_symbol}
+    # @return [Result]
+    def analyze(symbol, root: Dir.pwd, **)
+      analyzer(root: root).inspect_symbol(symbol, **)
+    end
+
+    # Analyses everything changed between +base+ and +head+.
+    #
+    # @param base [String] a Git ref
+    # @param head [String, nil] a Git ref, or nil to compare against the working tree
+    # @param root [String] project root
+    # @return [Result]
+    def diff(base, head: nil, root: Dir.pwd, **)
+      analyzer(root: root).diff(base: base, head: head, **)
+    end
+
+    # Ranked test files likely relevant to a symbol.
+    #
+    # @param symbol [String]
+    # @return [Array<String>] project-relative test paths, most relevant first
+    def tests_for(symbol, root: Dir.pwd, **)
+      analyze(symbol, root: root, **).test_files
+    end
+
+    private
+
+    def analyzer(root:)
+      Analyzer.new(project: Project.new(root: root))
+    end
+  end
+end
+
+require_relative "ripple_effect/configuration"
+require_relative "ripple_effect/project"
+require_relative "ripple_effect/risk"
+require_relative "ripple_effect/result"
+require_relative "ripple_effect/cache_store"
+require_relative "ripple_effect/static_index/adapter"
+require_relative "ripple_effect/static_index/rubydex_adapter"
+require_relative "ripple_effect/extractors/base"
+require_relative "ripple_effect/extractors/ruby_structure"
+require_relative "ripple_effect/extractors/rails_associations"
+require_relative "ripple_effect/extractors/rails_callbacks"
+require_relative "ripple_effect/extractors/rails_delegation"
+require_relative "ripple_effect/extractors/rails_jobs"
+require_relative "ripple_effect/extractors/rails_mailers"
+require_relative "ripple_effect/extractors/rails_routes"
+require_relative "ripple_effect/extractors/rails_views"
+require_relative "ripple_effect/extractors/test_conventions"
+require_relative "ripple_effect/traversal/impact_walker"
+require_relative "ripple_effect/diff/git"
+require_relative "ripple_effect/diff/hunk"
+require_relative "ripple_effect/diff/changed_symbol_resolver"
+require_relative "ripple_effect/formatters/text"
+require_relative "ripple_effect/formatters/json"
+require_relative "ripple_effect/formatters/dot"
+require_relative "ripple_effect/analyzer"