ripple_effect 0.1.0

data/lib/ripple_effect/diff/changed_symbol_resolver.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "hunk"
+require_relative "../diagnostic"
+
+module RippleEffect
+  module Diff
+    # Works out which symbols a diff actually changed.
+    #
+    # Treating every declaration in a touched file as changed gives a one-line fix
+    # an enormous, useless blast radius. Instead each changed line range maps to
+    # the smallest declaration enclosing it.
+    #
+    # Deleted code is the awkward case: it only exists in the base revision, so
+    # that content is parsed separately from the index of the current tree.
+    class ChangedSymbolResolver
+      # A symbol the diff touched.
+      Changed = Struct.new(:node, :path, :reason, keyword_init: true)
+
+      # @param project [Project]
+      # @param index [StaticIndex::Adapter] index of the current tree
+      # @param graph [Graph]
+      # @param git [Git]
+      def initialize(project:, index:, graph:, git:)
+        @project = project
+        @index = index
+        @graph = graph
+        @git = git
+        @diagnostics = []
+      end
+
+      # @return [Array<Diagnostic>] collected while resolving
+      attr_reader :diagnostics
+
+      # Resolves a set of Git changes into changed graph nodes.
+      #
+      # @param changes [Array<Git::Change>]
+      # @param base [String] the base ref, needed to read deleted content
+      # @param head [String, nil]
+      # @return [Array<Node>] deduplicated, sorted by ID
+      def resolve(changes:, base:, head: nil)
+        nodes = {}
+
+        changes.each do |change|
+          flag_global_file(change)
+
+          if change.deleted?
+            resolve_deleted_file(change, base, nodes)
+          elsif change.ruby?
+            resolve_ruby_change(change, base, head, nodes)
+          else
+            add_file_node(change.path, nodes)
+          end
+        end
+
+        nodes.values.sort_by(&:id)
+      end
+
+      private
+
+      # A change to a boot-impact file can affect almost anything, so we record it
+      # rather than let a narrow answer look authoritative.
+      def flag_global_file(change)
+        return unless @project.global_file?(change.path)
+
+        @diagnostics << Diagnostic.new(
+          code: "global_file_changed",
+          severity: :warning,
+          path: change.path,
+          message: "#{change.path} affects application boot or configuration; " \
+                   "impact may be broader than the graph shows"
+        )
+      end
+
+      def resolve_ruby_change(change, base, head, nodes)
+        if change.renamed?
+          @diagnostics << Diagnostic.new(
+            code: "renamed_file",
+            severity: :info,
+            path: change.path,
+            message: "renamed from #{change.old_path}"
+          )
+        end
+
+        hunks = Hunk.parse(@git.file_diff(base: base, head: head, path: change.path))
+
+        if hunks.empty?
+          add_file_node(change.path, nodes)
+          return
+        end
+
+        added = map_new_lines(change.path, hunks, nodes)
+        deleted = map_deleted_lines(change, base, nodes)
+
+        return if added || deleted
+
+        # We saw hunks but could attribute none of them to a declaration.
+        @diagnostics << Diagnostic.new(
+          code: "unmapped_changed_lines",
+          severity: :warning,
+          path: change.path,
+          message: "could not map changed lines in #{change.path} to a declaration; " \
+                   "treating the whole file as changed"
+        )
+        add_file_node(change.path, nodes)
+      end
+
+      # Added and modified lines exist in the current tree, so the live index can
+      # answer which declaration encloses them.
+      def map_new_lines(path, hunks, nodes)
+        matched = false
+
+        hunks.each do |hunk|
+          range = hunk.new_range
+          next unless range
+
+          declarations = range.filter_map { |line| @index.declaration_at(path: path, line: line) }.uniq
+
+          if declarations.empty?
+            # Lines inside a file but outside any declaration: requires,
+            # constants, or a class body statement. The file itself changed.
+            matched = true if add_file_node(path, nodes)
+            next
+          end
+
+          declarations.each do |declaration|
+            matched = true if add_declaration_node(declaration, nodes)
+          end
+        end
+
+        matched
+      end
+
+      # Deleted lines exist only in the base revision.
+      def map_deleted_lines(change, base, nodes)
+        deletions = Hunk.parse(@git.file_diff(base: base, head: nil, path: change.path))
+                        .select { |hunk| hunk.old_count.positive? }
+        return false if deletions.empty?
+
+        source = @git.show(ref: base, path: change.old_path || change.path)
+        return false if source.nil?
+
+        outline = Outline.parse(source)
+        matched = false
+
+        deletions.each do |hunk|
+          range = hunk.old_range
+          next unless range
+
+          range.filter_map { |line| outline.declaration_at(line) }.uniq.each do |name|
+            matched = true if add_named_node(name, change.path, nodes)
+          end
+        end
+
+        matched
+      end
+
+      # A file that no longer exists has no current declarations; we record what it
+      # used to define so its former dependents still show up.
+      def resolve_deleted_file(change, base, nodes)
+        @diagnostics << Diagnostic.new(
+          code: "deleted_file",
+          severity: :warning,
+          path: change.path,
+          message: "#{change.path} was deleted; anything that referenced it may break"
+        )
+
+        return unless change.ruby?
+
+        source = @git.show(ref: base, path: change.path)
+        return if source.nil?
+
+        Outline.parse(source).names.each { |name| add_named_node(name, change.path, nodes) }
+      end
+
+      def add_declaration_node(declaration, nodes)
+        node = @graph.find_symbol(declaration.qualified_name).find { |candidate| candidate.path == declaration.path }
+        return false unless node
+
+        nodes[node.id] = node
+        true
+      end
+
+      # Looks a base-revision name up in the current graph.
+      #
+      # A deleted method no longer exists to be looked up, but its former owner
+      # usually does, and dependents of the class are what a deletion is most
+      # likely to break. Fall back to the owner rather than losing the change.
+      def add_named_node(name, _path, nodes)
+        matches = @graph.find_symbol(name)
+        matches = @graph.find_symbol(owner_of(name)) if matches.empty?
+        return false if matches.empty?
+
+        matches.each { |node| nodes[node.id] = node }
+        true
+      end
+
+      # "BillingService#refund" -> "BillingService"
+      def owner_of(name)
+        name.to_s.split(/[#.]/).first.to_s
+      end
+
+      def add_file_node(path, nodes)
+        node = @graph.node("file:#{path}")
+        return false unless node
+
+        nodes[node.id] = node
+        true
+      end
+
+      # A line-to-declaration map for arbitrary source text, used for content that
+      # is not in the current tree and therefore not in the index.
+      class Outline
+        Entry = Struct.new(:name, :start_line, :end_line, keyword_init: true)
+
+        attr_reader :entries
+
+        def initialize(entries)
+          @entries = entries
+        end
+
+        # @param source [String] Ruby source
+        # @return [Outline] empty when the source does not parse
+        def self.parse(source)
+          result = Prism.parse(source)
+          return new([]) unless result.success?
+
+          entries = []
+          walk(result.value, nil, entries)
+          new(entries)
+        end
+
+        # @return [Array<String>] every declared name
+        def names
+          entries.map(&:name)
+        end
+
+        # The innermost declaration covering +line+.
+        #
+        # @return [String, nil]
+        def declaration_at(line)
+          covering = entries.select { |entry| line.between?(entry.start_line, entry.end_line) }
+          covering.min_by { |entry| entry.end_line - entry.start_line }&.name
+        end
+
+        def self.walk(node, namespace, entries)
+          return unless node
+
+          node.compact_child_nodes.each do |child|
+            case child
+            when Prism::ClassNode, Prism::ModuleNode
+              name = qualify(namespace, constant_name(child.constant_path))
+              if name
+                entries << Entry.new(name: name, start_line: child.location.start_line,
+                                     end_line: child.location.end_line)
+              end
+              walk(child.body, name || namespace, entries)
+            when Prism::DefNode
+              separator = child.receiver ? "." : "#"
+              name = namespace ? "#{namespace}#{separator}#{child.name}" : child.name.to_s
+              entries << Entry.new(name: name, start_line: child.location.start_line,
+                                   end_line: child.location.end_line)
+            else
+              walk(child, namespace, entries)
+            end
+          end
+        end
+
+        def self.constant_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parent = node.parent ? constant_name(node.parent) : nil
+            child = node.name&.to_s
+            return nil unless child
+
+            parent ? "#{parent}::#{child}" : child
+          end
+        end
+
+        def self.qualify(namespace, name)
+          return nil if name.nil?
+
+          namespace ? "#{namespace}::#{name}" : name
+        end
+
+        private_class_method :walk, :constant_name, :qualify
+      end
+    end
+  end
+end

data/lib/ripple_effect/diff/git.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../error"
+
+module RippleEffect
+  module Diff
+    # A minimal, safe Git client.
+    #
+    # Every invocation passes an argument array to {Open3.capture3}, so a ref like
+    # `; rm -rf /` is a ref that does not exist rather than a shell command. No Git
+    # output is ever interpolated back into another command.
+    class Git
+      # One changed file in a diff.
+      #
+      # @!attribute status
+      #   @return [Symbol] :added, :modified, :deleted, :renamed, or :other
+      Change = Struct.new(:status, :path, :old_path, keyword_init: true) do
+        def deleted? = status == :deleted
+        def added? = status == :added
+        def renamed? = status == :renamed
+        def ruby? = path.to_s.end_with?(".rb")
+      end
+
+      STATUS_CODES = {
+        "A" => :added, "M" => :modified, "D" => :deleted,
+        "R" => :renamed, "C" => :added, "T" => :modified
+      }.freeze
+
+      # @param root [String] the repository working directory
+      def initialize(root:)
+        @root = root
+      end
+
+      # @return [Boolean] true when +root+ is inside a Git work tree
+      def repository?
+        output, status = run("rev-parse", "--is-inside-work-tree")
+        status.success? && output.strip == "true"
+      rescue GitError
+        false
+      end
+
+      # @raise [GitError] unless +root+ is a Git work tree
+      def ensure_repository!
+        return if repository?
+
+        raise GitError, "#{@root} is not a Git repository"
+      end
+
+      # @param ref [String]
+      # @return [Boolean] true when the ref resolves
+      def ref?(ref)
+        _, status = run("rev-parse", "--verify", "--quiet", "#{ref}^{commit}")
+        status.success?
+      end
+
+      # @raise [GitError] when the ref does not resolve
+      def ensure_ref!(ref)
+        return if ref?(ref)
+
+        raise GitError, "unknown Git ref: #{ref}"
+      end
+
+      # Files changed between +base+ and +head+.
+      #
+      # With no +head+ the comparison is against the working tree, including both
+      # staged and unstaged changes: the state about to be committed.
+      #
+      # @param base [String] a Git ref
+      # @param head [String, nil] a Git ref, or nil for the working tree
+      # @return [Array<Change>] sorted by path
+      def changed_files(base:, head: nil)
+        ensure_repository!
+        ensure_ref!(base)
+        ensure_ref!(head) if head
+
+        args = ["diff", "--name-status", "--find-renames", "-z", base]
+        args << head if head
+
+        output, status = run(*args)
+        raise GitError, "git diff failed: #{output}" unless status.success?
+
+        changes = parse_name_status(output)
+        # `git diff` cannot see a file Git has never heard of, but a new,
+        # unstaged file is very much part of what the developer is about to commit.
+        changes += untracked_files if head.nil?
+
+        changes.uniq(&:path).sort_by(&:path)
+      end
+
+      # @return [Array<Change>] files present in the working tree but not in Git
+      def untracked_files
+        output, status = run("ls-files", "--others", "--exclude-standard", "-z")
+        return [] unless status.success?
+
+        output.split("\0").reject(&:empty?).map { |path| Change.new(status: :added, path: path, old_path: nil) }
+      end
+
+      # The unified diff for one file, with no context, so that every reported line
+      # is a line that actually changed.
+      #
+      # @return [String] raw diff text, empty when nothing changed
+      def file_diff(base:, path:, head: nil)
+        args = ["diff", "--unified=0", "--find-renames", base]
+        args << head if head
+        args += ["--", path]
+
+        output, status = run(*args)
+        raise GitError, "git diff failed for #{path}: #{output}" unless status.success?
+
+        output
+      end
+
+      # Reads a file's contents at a revision, for working out what a deletion removed.
+      #
+      # @return [String, nil] contents, or nil when the path did not exist there
+      def show(ref:, path:)
+        output, status = run("show", "#{ref}:#{path}")
+        status.success? ? output : nil
+      end
+
+      # @return [String] the repository's current HEAD SHA
+      def head_sha
+        output, status = run("rev-parse", "HEAD")
+        raise GitError, "could not resolve HEAD" unless status.success?
+
+        output.strip
+      end
+
+      private
+
+      # `-z` output is NUL-separated, which is what makes paths containing spaces,
+      # quotes or newlines safe to parse.
+      def parse_name_status(output)
+        fields = output.split("\0")
+        changes = []
+        index = 0
+
+        while index < fields.length
+          code = fields[index]
+          index += 1
+          next if code.nil? || code.empty?
+
+          status = STATUS_CODES.fetch(code[0], :other)
+
+          if status == :renamed
+            old_path = fields[index]
+            new_path = fields[index + 1]
+            index += 2
+            next if new_path.nil?
+
+            changes << Change.new(status: :renamed, path: new_path, old_path: old_path)
+          else
+            path = fields[index]
+            index += 1
+            next if path.nil?
+
+            changes << Change.new(status: status, path: path, old_path: nil)
+          end
+        end
+
+        changes
+      end
+
+      def run(*)
+        stdout, stderr, status = Open3.capture3("git", *, chdir: @root)
+        [status.success? ? stdout : "#{stdout}#{stderr}", status]
+      rescue Errno::ENOENT
+        raise GitError, "git executable not found on PATH"
+      rescue SystemCallError => e
+        raise GitError, "git invocation failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ripple_effect/diff/hunk.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  module Diff
+    # A contiguous run of changed lines within one file.
+    #
+    # Two line ranges matter and they are not the same: +new_range+ addresses the
+    # current file (where added and modified code lives), while +old_range+
+    # addresses the base revision (the only place deleted code still exists).
+    class Hunk
+      HEADER = /\A@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
+
+      attr_reader :old_start, :old_count, :new_start, :new_count
+
+      def initialize(old_start:, old_count:, new_start:, new_count:)
+        @old_start = old_start
+        @old_count = old_count
+        @new_start = new_start
+        @new_count = new_count
+        freeze
+      end
+
+      # Parses every hunk header out of a unified diff.
+      #
+      # @param diff [String] output of `git diff --unified=0`
+      # @return [Array<Hunk>]
+      def self.parse(diff)
+        diff.to_s.each_line.filter_map do |line|
+          match = HEADER.match(line)
+          next unless match
+
+          new(
+            old_start: match[1].to_i,
+            old_count: match[2] ? match[2].to_i : 1,
+            new_start: match[3].to_i,
+            new_count: match[4] ? match[4].to_i : 1
+          )
+        end
+      end
+
+      # Lines touched in the current revision.
+      #
+      # A zero count means a pure deletion: nothing was added at this point, so
+      # there are no lines in the new file to attribute the change to.
+      #
+      # @return [Range, nil]
+      def new_range
+        return nil if new_count.zero?
+
+        new_start..(new_start + new_count - 1)
+      end
+
+      # Lines touched in the base revision.
+      #
+      # @return [Range, nil]
+      def old_range
+        return nil if old_count.zero?
+
+        old_start..(old_start + old_count - 1)
+      end
+
+      # @return [Boolean] true when this hunk only removed lines
+      def deletion_only?
+        new_count.zero? && old_count.positive?
+      end
+
+      # @return [Boolean] true when this hunk only added lines
+      def addition_only?
+        old_count.zero? && new_count.positive?
+      end
+
+      def to_h
+        {
+          "old_start" => old_start, "old_count" => old_count,
+          "new_start" => new_start, "new_count" => new_count
+        }
+      end
+    end
+  end
+end

data/lib/ripple_effect/edge.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "confidence"
+
+module RippleEffect
+  # A directed, evidenced relationship between two {Node}s.
+  #
+  # The direction is always:
+  #
+  #   from_id *depends on / invokes / references* into_id
+  #
+  # So walking edges backwards from a changed node finds its dependents.
+  class Edge
+    TYPES = %i[
+      constant_reference
+      method_call
+      inheritance
+      include
+      prepend
+      extend
+      association
+      callback
+      delegate
+      route_handler
+      job_enqueue
+      mailer_delivery
+      test_convention
+      file_reference
+    ].freeze
+
+    # Human-facing phrasing for each edge type, used by the text formatter.
+    DESCRIPTIONS = {
+      constant_reference: "references constant",
+      method_call: "calls method",
+      inheritance: "inherits from",
+      include: "includes",
+      prepend: "prepends",
+      extend: "extends",
+      association: "association to",
+      callback: "callback invokes",
+      delegate: "delegates to",
+      route_handler: "route dispatches to",
+      job_enqueue: "enqueues job",
+      mailer_delivery: "delivers mail via",
+      test_convention: "conventionally tests",
+      file_reference: "references file"
+    }.freeze
+
+    attr_reader :from_id, :into_id, :type, :evidence, :confidence, :location, :metadata
+
+    # @param from_id [String] the dependent node's ID
+    # @param into_id [String] the depended-upon node's ID
+    # @param type [Symbol] one of {TYPES}
+    # @param evidence [String] a stable evidence code, e.g. "rails.after_commit"
+    # @param confidence [Symbol] a {Confidence} band
+    # @param location [String, nil] "path:line" where the relationship was observed
+    # @param metadata [Hash] JSON-compatible extra facts
+    def initialize(from_id:, into_id:, type:, evidence:, confidence:, location: nil, metadata: {})
+      @from_id = from_id.to_s.freeze
+      @into_id = into_id.to_s.freeze
+      @type = self.class.cast_type(type)
+      @evidence = evidence.to_s.freeze
+      @confidence = Confidence.cast(confidence)
+      @location = location&.to_s&.freeze
+      @metadata = metadata.freeze
+      freeze
+    end
+
+    # @return [Symbol] the canonical edge type
+    # @raise [ArgumentError] on an unknown type
+    def self.cast_type(type)
+      symbol = type.to_s.to_sym
+      return symbol if TYPES.include?(symbol)
+
+      raise ArgumentError, "unknown edge type #{type.inspect}"
+    end
+
+    # @return [String] a stable identity used for duplicate suppression
+    def key
+      "#{from_id}|#{into_id}|#{type}|#{evidence}"
+    end
+
+    # @return [String] a short human explanation, e.g. "callback invokes (rails.after_commit)"
+    def description
+      "#{DESCRIPTIONS.fetch(type, type.to_s)} (#{evidence})"
+    end
+
+    # @return [Hash] JSON-compatible representation with deterministic key order
+    def to_h
+      {
+        "from_id" => from_id,
+        "into_id" => into_id,
+        "type" => type.to_s,
+        "evidence" => evidence,
+        "confidence" => confidence.to_s,
+        "location" => location,
+        "metadata" => metadata.to_h { |k, v| [k.to_s, v.is_a?(Symbol) ? v.to_s : v] }
+      }
+    end
+
+    def ==(other)
+      other.is_a?(Edge) && other.key == key
+    end
+    alias eql? ==
+
+    def hash
+      key.hash
+    end
+
+    def inspect
+      "#<RippleEffect::Edge #{from_id} -#{type}-> #{into_id} (#{confidence})>"
+    end
+  end
+end

data/lib/ripple_effect/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  # Base class for every error raised by Ripple Effect.
+  class Error < StandardError; end
+
+  # Raised when `.ripple-effect.yml` is missing required keys or holds invalid values.
+  class ConfigurationError < Error; end
+
+  # Raised when the project root is unusable (missing, not a directory, unreadable).
+  class ProjectError < Error; end
+
+  # Raised when the static index cannot be initialised at all.
+  #
+  # A failure to index a *single* file is a diagnostic, not an error.
+  class IndexError < Error; end
+
+  # Raised when a user-supplied symbol query cannot be resolved to exactly one declaration.
+  class QueryError < Error; end
+
+  # Raised when a Git invocation fails or the project is not a Git work tree.
+  class GitError < Error; end
+end