ripple_effect 0.1.0

data/lib/ripple_effect/formatters/dot.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  module Formatters
+    # Graphviz DOT output, for piping into `dot -Tsvg`.
+    #
+    # Only the impacted subgraph is emitted, not the whole project: a 5,000-file
+    # application's full graph is not something anyone can read.
+    class Dot
+      SHAPES = {
+        route: "house", job: "component", callback: "diamond", mailer_action: "note",
+        test_file: "folder", file: "folder", class: "box", module: "box3d"
+      }.freeze
+
+      STYLES = { high: "solid", medium: "dashed", low: "dotted" }.freeze
+
+      # @param result [Result]
+      def initialize(result:)
+        @result = result
+      end
+
+      # @return [String]
+      def render
+        lines = ["digraph ripple_effect {", "  rankdir=RL;", "  node [fontname=\"Helvetica\", fontsize=10];",
+                 "  edge [fontname=\"Helvetica\", fontsize=8];"]
+
+        @result.changed_nodes.each do |node|
+          lines << "  #{quote(node.id)} [label=#{quote(node.name)}, shape=#{shape(node)}, " \
+                   "style=filled, fillcolor=\"#ffe0e0\"];"
+        end
+
+        @result.impacts.each do |impact|
+          node = impact.node
+          lines << "  #{quote(node.id)} [label=#{quote(node.name)}, shape=#{shape(node)}];"
+        end
+
+        edges.each do |edge|
+          lines << "  #{quote(edge.from_id)} -> #{quote(edge.into_id)} " \
+                   "[label=#{quote(edge.type.to_s)}, style=#{STYLES.fetch(edge.confidence, 'solid')}];"
+        end
+
+        lines << "}"
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      # Every edge that appears in some impact's evidence path, deduplicated.
+      def edges
+        seen = {}
+
+        @result.impacts.flat_map(&:evidence_path).each_with_object([]) do |edge, result|
+          next if seen[edge.key]
+
+          seen[edge.key] = true
+          result << edge
+        end
+      end
+
+      def shape(node)
+        SHAPES.fetch(node.kind, "ellipse")
+      end
+
+      def quote(text)
+        "\"#{text.to_s.gsub('\\', '\\\\\\\\').gsub('"', '\\"')}\""
+      end
+    end
+  end
+end

data/lib/ripple_effect/formatters/json.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RippleEffect
+  module Formatters
+    # Machine-readable output.
+    #
+    # This is a public interface with a schema version, so it is generated from
+    # {Result#to_h} without reordering or filtering: what the library exposes and
+    # what the CLI prints are the same document.
+    class Json
+      # @param result [Result]
+      # @param pretty [Boolean]
+      def initialize(result:, pretty: true)
+        @result = result
+        @pretty = pretty
+      end
+
+      # @return [String]
+      def render
+        payload = @result.to_h
+        "#{@pretty ? JSON.pretty_generate(payload) : JSON.generate(payload)}\n"
+      end
+
+      # The error envelope. Errors in JSON mode are still JSON, so a consumer
+      # never has to parse a stack trace out of stderr.
+      #
+      # @param error [Exception]
+      # @param code [String] a stable error code
+      # @return [String]
+      def self.error(error, code: "error")
+        payload = JSON.pretty_generate(
+          "schema_version" => SCHEMA_VERSION,
+          "tool" => { "name" => "ripple_effect", "version" => VERSION },
+          "error" => { "code" => code, "type" => error.class.name, "message" => error.message }
+        )
+
+        "#{payload}\n"
+      end
+    end
+  end
+end

data/lib/ripple_effect/formatters/text.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  module Formatters
+    # Human-readable output.
+    #
+    # Impacts are grouped by the kind of evidence that reached them, because "this
+    # is a callback" and "this is a method call" are different claims and deserve
+    # to be read differently.
+    class Text
+      SECTIONS = [
+        ["Direct dependents", ->(impact) { impact.depth == 1 && code_edge?(impact) }],
+        ["Rails semantic dependents", ->(impact) { rails_edge?(impact) }],
+        ["Transitive dependents", ->(impact) { impact.depth > 1 && code_edge?(impact) }]
+      ].freeze
+
+      # Edges that hold the graph together: a file "depending on" the classes it
+      # declares, a class on the methods it defines. Needed for traversal and for
+      # mapping a diff onto symbols, but reporting them as dependents buries the
+      # real answer. JSON output keeps them.
+      STRUCTURAL_EVIDENCE = %w[ruby.file_declares ruby.defines_method].freeze
+
+      # @param result [Result]
+      # @param verbose [Boolean] include stats and every diagnostic
+      def initialize(result:, verbose: false)
+        @result = result
+        @verbose = verbose
+      end
+
+      # @return [String]
+      def render
+        lines = []
+        lines.concat(header)
+        lines.concat(impact_sections)
+        lines.concat(tests_section)
+        lines.concat(blast_radius_section)
+        lines.concat(diagnostics_section)
+        lines.concat(stats_section) if @verbose
+        "#{lines.join("\n").rstrip}\n"
+      end
+
+      class << self
+        # A callback, route, job, mailer, association or delegation, as opposed
+        # to a plain Ruby reference.
+        def rails_edge?(impact)
+          edge = impact.reason
+          return false unless edge
+
+          %i[callback route_handler job_enqueue mailer_delivery association delegate].include?(edge.type)
+        end
+
+        def code_edge?(impact)
+          return false if rails_edge?(impact)
+          return false if impact.node.kind == :test_file
+          return false if structural?(impact)
+
+          true
+        end
+
+        # @return [Boolean] true when this impact exists only because of graph
+        #   containment, not because of a real reference
+        def structural?(impact)
+          edge = impact.reason
+          return false unless edge
+
+          STRUCTURAL_EVIDENCE.include?(edge.evidence)
+        end
+      end
+
+      private
+
+      def header
+        lines = []
+
+        if @result.query_type == :diff
+          lines << "#{@result.changed_nodes.length} changed #{plural(@result.changed_nodes.length, 'symbol')} " \
+                   "detected in #{@result.query_value}"
+          lines << ""
+          @result.changed_nodes.each { |node| lines << "  #{node.name}  (#{node.location})" }
+        else
+          lines << @result.query_value
+          changed = @result.changed_nodes.first
+          lines << "  #{changed.location}" if changed
+        end
+
+        lines << ""
+        lines
+      end
+
+      def impact_sections
+        lines = []
+        rendered = {}
+
+        SECTIONS.each do |title, matcher|
+          matching = @result.impacts.reject { |impact| rendered[impact.node.id] }
+                            .select { |impact| matcher.call(impact) }
+          next if matching.empty?
+
+          lines << title
+          matching.each do |impact|
+            rendered[impact.node.id] = true
+            lines.concat(impact_lines(impact))
+          end
+          lines << ""
+        end
+
+        if lines.empty?
+          lines << "No dependents found at the current confidence threshold."
+          lines << ""
+        end
+
+        lines
+      end
+
+      def impact_lines(impact)
+        edge = impact.reason
+        location = impact.node.location.ljust(42)
+        # A file or template node's name is its path, which would just repeat the
+        # location; label it by what it is instead.
+        label = impact.node.name == impact.node.path ? kind_label(impact.node) : impact.node.name
+
+        [
+          "  #{location} #{label}",
+          "    because: #{edge ? edge.description : 'reachable'}#{at(edge)}",
+          "    confidence: #{impact.confidence}, depth: #{impact.depth}"
+        ]
+      end
+
+      def kind_label(node)
+        case node.kind
+        when :view then node.metadata["partial"] ? "(partial)" : "(template)"
+        when :test_file then "(test)"
+        else "(file)"
+        end
+      end
+
+      def at(edge)
+        edge&.location ? " at #{edge.location}" : ""
+      end
+
+      def tests_section
+        return [] if @result.tests.empty?
+
+        lines = ["Likely affected tests"]
+        @result.tests.each do |test|
+          lines << "  #{test.path.ljust(46)} #{test.reason} (#{test.confidence})"
+        end
+        lines << ""
+        lines
+      end
+
+      def blast_radius_section
+        risk = @result.risk
+
+        lines = [
+          "Blast radius",
+          "  direct nodes: #{@result.direct_count}",
+          "  transitive nodes: #{@result.transitive_count}",
+          "  max depth: #{@result.max_depth}",
+          "  risk: #{risk.level}"
+        ]
+
+        unless risk.reasons.empty?
+          lines << "  because:"
+          risk.reasons.each { |reason| lines << "    #{reason}" }
+        end
+
+        lines << ""
+        lines
+      end
+
+      def diagnostics_section
+        shown = @verbose ? @result.diagnostics : @result.diagnostics.select { |d| d.severity == :warning }
+        return [] if shown.empty?
+
+        lines = ["Diagnostics"]
+        shown.first(@verbose ? shown.length : 10).each { |diagnostic| lines << "  #{diagnostic}" }
+
+        hidden = shown.length - 10
+        lines << "  (#{hidden} more; re-run with --verbose)" if !@verbose && hidden.positive?
+        lines << ""
+        lines
+      end
+
+      def stats_section
+        lines = ["Stats"]
+        @result.stats.each { |key, value| lines << "  #{key}: #{value}" }
+        lines << ""
+        lines
+      end
+
+      def plural(count, word)
+        count == 1 ? word : "#{word}s"
+      end
+    end
+  end
+end

data/lib/ripple_effect/graph.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "node"
+require_relative "edge"
+require_relative "confidence"
+
+module RippleEffect
+  # The dependency graph: nodes plus evidenced, directed edges, with forward and
+  # reverse adjacency maintained as edges are added.
+  #
+  # Edges point from dependent to dependency, so {#dependents} walks the reverse
+  # index and answers "what could break if this changes?".
+  #
+  # Iteration order is insertion order, and every traversal sorts its frontier by
+  # node ID, so identical input always produces identical output.
+  class Graph
+    def initialize
+      @nodes = {}
+      @outgoing = Hash.new { |hash, key| hash[key] = [] }
+      @incoming = Hash.new { |hash, key| hash[key] = [] }
+      @edge_keys = {}
+      @by_path = Hash.new { |hash, key| hash[key] = [] }
+      @by_name = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    # Adds a node, or returns the existing node when the ID is already present.
+    #
+    # @param node [Node]
+    # @return [Node] the node stored under this ID
+    def add_node(node)
+      existing = @nodes[node.id]
+      return existing if existing
+
+      @nodes[node.id] = node
+      @by_path[node.path] << node
+      @by_name[node.qualified_name] << node if node.qualified_name
+      @by_name[node.name] << node if node.name != node.qualified_name
+      node
+    end
+
+    # Adds an edge unless an identical one (same endpoints, type and evidence)
+    # already exists.
+    #
+    # @param edge [Edge]
+    # @return [Boolean] true when the edge was newly added
+    def add_edge(edge)
+      return false if @edge_keys.key?(edge.key)
+
+      @edge_keys[edge.key] = edge
+      @outgoing[edge.from_id] << edge
+      @incoming[edge.into_id] << edge
+      true
+    end
+
+    # @return [Node, nil]
+    def node(id)
+      @nodes[id]
+    end
+
+    # @return [Boolean]
+    def node?(id)
+      @nodes.key?(id)
+    end
+
+    # @return [Array<Node>]
+    def nodes
+      @nodes.values
+    end
+
+    # @return [Array<Edge>]
+    def edges
+      @edge_keys.values
+    end
+
+    def node_count = @nodes.size
+    def edge_count = @edge_keys.size
+
+    # Edges where +id+ is the dependent.
+    # @return [Array<Edge>]
+    def outgoing(id)
+      @outgoing.key?(id) ? @outgoing[id] : []
+    end
+
+    # Edges where +id+ is the dependency.
+    # @return [Array<Edge>]
+    def incoming(id)
+      @incoming.key?(id) ? @incoming[id] : []
+    end
+
+    # @return [Array<Node>] every node declared in +path+
+    def nodes_by_path(path)
+      @by_path.key?(path) ? @by_path[path] : []
+    end
+
+    # @return [Array<String>] every indexed path, sorted
+    def paths
+      @by_path.keys.sort
+    end
+
+    # Nodes that depend on +id+, directly or transitively.
+    #
+    # @param id [String]
+    # @param depth [Integer, nil] maximum hops, nil for unlimited
+    # @param min_confidence [Symbol] skip edges weaker than this band
+    # @return [Array<Node>] sorted by ID
+    def dependents(id, depth: nil, min_confidence: Confidence::LOW)
+      walk(id, direction: :incoming, depth: depth, min_confidence: min_confidence)
+    end
+
+    # Nodes that +id+ depends on, directly or transitively.
+    #
+    # @see #dependents
+    # @return [Array<Node>] sorted by ID
+    def dependencies(id, depth: nil, min_confidence: Confidence::LOW)
+      walk(id, direction: :outgoing, depth: depth, min_confidence: min_confidence)
+    end
+
+    # Finds nodes whose qualified name or display name matches +query+ exactly.
+    #
+    # Accepts both +User.find+ and +User::find+ for singleton methods; the returned
+    # nodes always use the canonical +User.find+ form.
+    #
+    # @param query [String]
+    # @return [Array<Node>] sorted by ID; empty when nothing matches
+    def find_symbol(query)
+      needle = normalize_query(query)
+      return [] unless @by_name.key?(needle)
+
+      @by_name[needle].uniq.sort_by(&:id)
+    end
+
+    # @return [Array<Node>] every node whose path matches, for file-shaped queries
+    def find_path(query)
+      nodes_by_path(query).sort_by(&:id)
+    end
+
+    # Normalises a user query into the canonical display form.
+    #
+    # @param query [String]
+    # @return [String]
+    def normalize_query(query)
+      text = query.to_s.strip
+      # `User::find` is a legal way to write a singleton call, but the constant
+      # separator is ambiguous: only rewrite when the last segment starts lowercase.
+      if (match = text.match(/\A(.+)::([a-z_][A-Za-z0-9_]*[?!=]?)\z/))
+        return "#{match[1]}.#{match[2]}"
+      end
+
+      text
+    end
+
+    # @return [Hash<Symbol, Integer>] node counts per kind, for `doctor` and stats
+    def counts_by_kind
+      nodes.each_with_object(Hash.new(0)) { |node, counts| counts[node.kind] += 1 }
+    end
+
+    private
+
+    # Breadth-first walk that returns reached nodes only. {Traversal::ImpactWalker}
+    # does the same walk while retaining evidence paths.
+    def walk(id, direction:, depth:, min_confidence:)
+      return [] unless node?(id)
+
+      visited = { id => true }
+      frontier = [id]
+      reached = []
+      hops = 0
+
+      while !frontier.empty? && (depth.nil? || hops < depth)
+        hops += 1
+        next_frontier = []
+
+        frontier.sort.each do |current|
+          edges_for(current, direction).each do |edge|
+            next unless Confidence.at_least?(edge.confidence, min_confidence)
+
+            neighbour = direction == :incoming ? edge.from_id : edge.into_id
+            next if visited[neighbour]
+
+            visited[neighbour] = true
+            found = @nodes[neighbour]
+            next unless found
+
+            reached << found
+            next_frontier << neighbour
+          end
+        end
+
+        frontier = next_frontier
+      end
+
+      reached.sort_by(&:id)
+    end
+
+    def edges_for(id, direction)
+      direction == :incoming ? incoming(id) : outgoing(id)
+    end
+  end
+end

data/lib/ripple_effect/node.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  # A single addressable thing in the analysed project: a file, a class, a method,
+  # a route, a callback, and so on.
+  #
+  # Nodes are value objects with deterministic string IDs. Two nodes with the same
+  # +id+ are considered equal, which is what lets the graph suppress duplicates that
+  # several extractors independently discover.
+  class Node
+    KINDS = %i[
+      file
+      class
+      module
+      instance_method
+      class_method
+      route
+      test_file
+      callback
+      association
+      job
+      mailer_action
+      view
+      unknown
+    ].freeze
+
+    attr_reader :id, :kind, :name, :qualified_name, :path, :start_line, :end_line, :metadata
+
+    # @param kind [Symbol] one of {KINDS}
+    # @param name [String] display name
+    # @param path [String] project-relative path
+    # @param qualified_name [String, nil] canonical symbol name, when the kind has one
+    # @param start_line [Integer, nil]
+    # @param end_line [Integer, nil]
+    # @param metadata [Hash] JSON-compatible extra facts
+    # @param id [String, nil] override the derived ID; normally left nil
+    def initialize(kind:, name:, path:, qualified_name: nil, start_line: nil, end_line: nil, metadata: {}, id: nil)
+      @kind = self.class.cast_kind(kind)
+      @name = name.to_s
+      @path = path.to_s
+      @qualified_name = qualified_name&.to_s
+      @start_line = start_line
+      @end_line = end_line
+      @metadata = deep_freeze(metadata)
+      @id = (id || derive_id).freeze
+      freeze
+    end
+
+    # @return [Symbol] the canonical kind
+    # @raise [ArgumentError] on an unknown kind
+    def self.cast_kind(kind)
+      symbol = kind.to_s.to_sym
+      return symbol if KINDS.include?(symbol)
+
+      raise ArgumentError, "unknown node kind #{kind.inspect}"
+    end
+
+    # @return [Boolean] true for instance and singleton methods
+    def method?
+      %i[instance_method class_method].include?(kind)
+    end
+
+    # @return [Boolean] true for classes and modules
+    def namespace?
+      %i[class module].include?(kind)
+    end
+
+    # @return [String] "path:line" for humans, or just the path when no line is known
+    def location
+      start_line ? "#{path}:#{start_line}" : path
+    end
+
+    # @return [Boolean] true when +line+ falls inside this node's line range
+    def covers_line?(line)
+      return false if start_line.nil?
+
+      line.between?(start_line, end_line || start_line)
+    end
+
+    # @return [Integer, nil] number of source lines spanned, nil when unknown
+    def span
+      return nil if start_line.nil?
+
+      (end_line || start_line) - start_line + 1
+    end
+
+    # @return [Hash] JSON-compatible representation with deterministic key order
+    def to_h
+      {
+        "id" => id,
+        "kind" => kind.to_s,
+        "name" => name,
+        "qualified_name" => qualified_name,
+        "path" => path,
+        "start_line" => start_line,
+        "end_line" => end_line,
+        "metadata" => stringify(metadata)
+      }
+    end
+
+    def ==(other)
+      other.is_a?(Node) && other.id == id
+    end
+    alias eql? ==
+
+    def hash
+      id.hash
+    end
+
+    def to_s
+      "#{kind}:#{name}"
+    end
+
+    def inspect
+      "#<RippleEffect::Node #{id}>"
+    end
+
+    private
+
+    # Deterministic, human-readable IDs. Location is included for method and
+    # namespace nodes so that a class reopened in two files does not collide.
+    def derive_id
+      case kind
+      when :instance_method, :class_method
+        "method:#{path}:#{qualified_name || name}"
+      when :class, :module
+        "#{kind}:#{path}:#{qualified_name || name}"
+      when :file, :test_file
+        "file:#{path}"
+      else
+        "#{kind}:#{path}:#{start_line || 0}:#{qualified_name || name}"
+      end
+    end
+
+    def stringify(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, stringify(v)] }
+      when Array then value.map { |v| stringify(v) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.transform_values { |v| deep_freeze(v) }.freeze
+      when Array then value.map { |v| deep_freeze(v) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+  end
+end