ripple_effect 0.1.0

data/lib/ripple_effect/project.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "error"
+require_relative "configuration"
+
+module RippleEffect
+  # The analysed repository: its root, its configuration, and the set of source
+  # files that configuration selects.
+  #
+  # Every path Ripple Effect reports is project-relative, and every path it reads is
+  # checked to be inside the root, so a stray symlink or a `../` in a config glob
+  # cannot pull in files from elsewhere on the machine.
+  class Project
+    # Directories that make a repository look like a Rails application. Used by
+    # `doctor` for advice only; analysis never requires them.
+    RAILS_MARKERS = ["app", "config", "config/routes.rb", "config/application.rb"].freeze
+
+    attr_reader :root, :configuration
+
+    # @param root [String] project root, absolute or relative
+    # @param configuration [Configuration, nil] loaded from the root when omitted
+    # @param config_path [String, nil] explicit config file path
+    # @raise [ProjectError] when the root does not exist or is not a directory
+    def initialize(root:, configuration: nil, config_path: nil)
+      expanded = File.expand_path(root.to_s)
+      raise ProjectError, "project root does not exist: #{expanded}" unless File.exist?(expanded)
+      raise ProjectError, "project root is not a directory: #{expanded}" unless File.directory?(expanded)
+
+      # Anchor on the canonical path, not on what the user typed.
+      #
+      # macOS and Windows filesystems are case-insensitive but case-preserving.
+      # `--root ~/code/appease` finds files in `~/code/AppEase`, and Dir.glob
+      # returns them with their real casing. Comparing those against the typed
+      # root then fails for every file and the analysis comes back empty with no
+      # error. Resolving symlinks here covers a symlinked root too.
+      @root = canonical_root(expanded).freeze
+      @root_pathname = Pathname.new(@root)
+      @configuration = configuration || Configuration.load(root: @root, path: config_path)
+    end
+
+    # Absolute paths of every file matching the include globs and surviving the
+    # exclude globs, sorted so that indexing order is deterministic.
+    #
+    # @return [Array<String>]
+    def source_files
+      @source_files ||= glob_all(configuration.include_patterns).sort
+    end
+
+    # Directories that are themselves Rails engines or gems, each with their own
+    # `app/` and `lib/`.
+    #
+    # Solidus and Spree are built this way, and plenty of applications keep an
+    # `engines/` directory. Such repos have no top-level `app/`, so the default
+    # patterns would match nothing. A directory qualifies only if it has an `app/`
+    # and declares itself a gem or engine, which keeps ordinary subdirectories out.
+    #
+    # @return [Array<String>] project-relative directory paths, sorted
+    def engine_roots
+      @engine_roots ||= begin
+        candidates = Dir.glob(File.join(root, "*/"), File::FNM_DOTMATCH) +
+                     Dir.glob(File.join(root, "*/*/"), File::FNM_DOTMATCH)
+
+        candidates.filter_map { |dir| engine_root_for(dir) }.uniq.sort
+      end
+    end
+
+    # @return [Array<String>] project-relative source paths, sorted
+    def source_paths
+      @source_paths ||= source_files.map { |path| relative_path(path) }
+    end
+
+    # Template files matching the configured view patterns.
+    #
+    # @return [Array<String>] project-relative paths, sorted
+    def view_paths
+      @view_paths ||= glob_all(configuration.view_patterns)
+                      .map { |path| relative_path(path) }
+                      .reject { |path| path.start_with?("/") }
+                      .sort
+    end
+
+    # @return [Array<String>] project-relative test paths, sorted
+    def test_paths
+      @test_paths ||= source_paths.select { |path| test_path?(path) }
+    end
+
+    # Membership lookup for indexed paths.
+    #
+    # Extractors ask this once per candidate path, so a linear scan over
+    # {#source_paths} would be quadratic on a large application.
+    #
+    # @param path [String] project-relative path
+    # @return [Boolean]
+    def indexed?(path)
+      @indexed_paths ||= source_paths.to_set
+
+      @indexed_paths.include?(path)
+    end
+
+    # @param path [String] project-relative path
+    # @return [Boolean] true for files under spec/ or test/
+    def test_path?(path)
+      path.start_with?("spec/", "test/")
+    end
+
+    # Converts an absolute path (or a file:// URI) into a project-relative path.
+    #
+    # @param path [String]
+    # @return [String] the relative path, or the input unchanged when outside the root
+    def relative_path(path)
+      absolute = normalize(path)
+      return absolute unless absolute.start_with?("#{root}/")
+
+      absolute[(root.length + 1)..]
+    end
+
+    # @param path [String] project-relative path
+    # @return [String] absolute path
+    def absolute_path(path)
+      File.expand_path(path, root)
+    end
+
+    # Reads a project file, refusing anything that resolves outside the root.
+    #
+    # @param path [String] project-relative path
+    # @return [String, nil] file contents, or nil when the file is missing
+    # @raise [ProjectError] when the path escapes the project root
+    def read(path)
+      absolute = absolute_path(path)
+      raise ProjectError, "refusing to read outside the project root: #{path}" unless inside_root?(absolute)
+      return nil unless File.file?(absolute)
+
+      File.read(absolute, encoding: Encoding::UTF_8)
+    end
+
+    # Whether a path resolves to somewhere inside the project.
+    #
+    # Symlinks are resolved before the comparison, so a link that sits inside the
+    # project but points outside it is rejected. A lexical check alone would let
+    # such a link through, which is the case this guard exists for.
+    #
+    # @return [Boolean]
+    def inside_root?(path)
+      absolute = normalize(path)
+      return true if absolute == root || absolute == real_root
+
+      resolved = resolve_symlinks(absolute)
+      return false if resolved.nil?
+
+      resolved.start_with?("#{real_root}/")
+    end
+
+    # @return [Boolean] true when the root looks like a Rails application
+    def rails_like?
+      RAILS_MARKERS.any? { |marker| File.exist?(File.join(root, marker)) }
+    end
+
+    # Detects the test framework in use, honouring an explicit config setting.
+    #
+    # @return [Symbol] :rspec, :minitest, or :unknown
+    def test_framework
+      configured = configuration.test_framework
+      return configured unless configured == :auto
+
+      return :rspec if File.directory?(File.join(root, "spec"))
+      return :minitest if File.directory?(File.join(root, "test"))
+
+      :unknown
+    end
+
+    # @param path [String] project-relative path
+    # @return [Boolean] true when the path matches a configured global/boot-impact glob
+    def global_file?(path)
+      configuration.unsafe_global_files.any? do |pattern|
+        File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB) ||
+          File.fnmatch?(pattern, path, File::FNM_EXTGLOB)
+      end
+    end
+
+    # @return [String] absolute path of the cache directory
+    def cache_directory
+      absolute_path(configuration.cache_directory)
+    end
+
+    private
+
+    # Expands patterns against the project root and, when engine discovery is on,
+    # against each discovered engine root as well.
+    def glob_all(patterns)
+      roots = [root]
+      roots += engine_roots.map { |dir| File.join(root, dir) } if configuration.discover_engines
+
+      matched = roots.flat_map do |base|
+        patterns.flat_map { |pattern| Dir.glob(File.join(base, pattern), File::FNM_DOTMATCH) }
+      end
+
+      matched.uniq
+             .select { |path| File.file?(path) }
+             .reject { |path| excluded?(path) }
+             .select { |path| inside_root?(path) }
+    end
+
+    # @return [String, nil] project-relative path when +dir+ is an engine root
+    def engine_root_for(dir)
+      absolute = dir.chomp("/")
+      relative = relative_path(absolute)
+      return nil if relative.start_with?("/") || relative.empty?
+      return nil if excluded?(absolute)
+      return nil unless File.directory?(File.join(absolute, "app"))
+
+      # A gemspec, or a Rails engine class, is what separates an engine from a
+      # directory that merely happens to contain something called `app`.
+      gem_like = !Dir.glob(File.join(absolute, "*.gemspec")).empty? ||
+                 !Dir.glob(File.join(absolute, "lib/**/engine.rb")).empty?
+
+      gem_like ? relative : nil
+    end
+
+    # @return [String] the filesystem's own spelling of this directory
+    def canonical_root(expanded)
+      File.realpath(expanded)
+    rescue SystemCallError
+      expanded
+    end
+
+    def real_root
+      @real_root ||= canonical_root(root)
+    end
+
+    # Resolves symlinks as far as the filesystem allows.
+    #
+    # A path that does not exist yet cannot be resolved, so resolve its nearest
+    # existing ancestor and re-append the remainder. Otherwise writing a new cache
+    # file would look like an escape attempt.
+    #
+    # @return [String, nil] nil when not even the root of the path exists
+    def resolve_symlinks(absolute)
+      File.realpath(absolute)
+    rescue SystemCallError
+      parent = File.dirname(absolute)
+      return nil if parent == absolute
+
+      resolved_parent = resolve_symlinks(parent)
+      resolved_parent && File.join(resolved_parent, File.basename(absolute))
+    end
+
+    def normalize(path)
+      text = path.to_s
+      text = text.delete_prefix("file://") if text.start_with?("file://")
+      File.expand_path(text, root)
+    end
+
+    def excluded?(absolute)
+      relative = relative_path(absolute)
+
+      configuration.exclude_patterns.any? do |pattern|
+        File.fnmatch?(pattern, relative, File::FNM_PATHNAME | File::FNM_EXTGLOB) ||
+          File.fnmatch?(pattern, relative, File::FNM_EXTGLOB) ||
+          relative.start_with?("#{pattern.sub(%r{/\*\*\z}, '')}/")
+      end
+    end
+  end
+end

data/lib/ripple_effect/result.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+module RippleEffect
+  # A ranked test file, with the evidence that made it relevant.
+  class TestSuggestion
+    # Strong evidence first. A test that references the changed code directly beats
+    # one that merely sits at the conventional path.
+    RANKS = {
+      "reference" => 0,
+      "rails_semantic" => 1,
+      "convention" => 2,
+      "heuristic" => 3
+    }.freeze
+
+    attr_reader :path, :reason, :confidence, :depth, :evidence
+
+    def initialize(path:, reason:, confidence:, depth:, evidence:)
+      @path = path
+      @reason = reason
+      @confidence = confidence
+      @depth = depth
+      @evidence = evidence
+      freeze
+    end
+
+    # @return [Integer] sort key; lower is more relevant
+    def rank
+      RANKS.fetch(reason, RANKS.size)
+    end
+
+    def to_h
+      {
+        "path" => path,
+        "reason" => reason,
+        "evidence" => evidence,
+        "confidence" => confidence.to_s,
+        "depth" => depth
+      }
+    end
+  end
+
+  # The answer to one question, in a form both humans and other tools can read.
+  #
+  # The hash produced by {#to_h} is a public interface: it carries a schema version
+  # and its ordering is deterministic, so a snapshot test of it is meaningful.
+  class Result
+    attr_reader :query_type, :query_value, :changed_nodes, :impacts, :tests,
+                :risk, :diagnostics, :stats
+
+    # @param query_type [Symbol] :symbol or :diff
+    # @param query_value [String] what was asked
+    # @param changed_nodes [Array<Node>]
+    # @param impacts [Array<Traversal::Impact>]
+    # @param tests [Array<TestSuggestion>]
+    # @param risk [Risk]
+    # @param diagnostics [Array<Diagnostic>]
+    # @param stats [Hash]
+    def initialize(query_type:, query_value:, changed_nodes:, impacts:, tests:, risk:, diagnostics:, stats: {})
+      @query_type = query_type
+      @query_value = query_value
+      @changed_nodes = changed_nodes.sort_by(&:id).freeze
+      @impacts = impacts.freeze
+      @reportable_impacts = impacts.reject { |impact| impact.node.kind == :file }.freeze
+      @tests = tests.freeze
+      @risk = risk
+      @diagnostics = diagnostics.uniq.sort_by { |d| [d.path.to_s, d.line || 0, d.code] }.freeze
+      @stats = stats.freeze
+      freeze
+    end
+
+    # @return [Array<Node>] every impacted node, shortest path first
+    def impacted_nodes
+      impacts.map(&:node)
+    end
+
+    # @return [Array<String>] ranked test paths, most relevant first
+    def test_files
+      tests.map(&:path)
+    end
+
+    # Impacts worth showing a human.
+    #
+    # File nodes exist so that a file-level change can reach the code it declares.
+    # They matter for traversal and for mapping a diff onto symbols, but as an
+    # answer they are noise, so summaries and risk leave them out.
+    #
+    # @return [Array<Traversal::Impact>]
+    attr_reader :reportable_impacts
+
+    # @return [Integer] the longest evidence path in the result
+    def max_depth
+      impacts.map(&:depth).max || 0
+    end
+
+    # @return [Integer] reportable impacts one hop from a changed node
+    def direct_count
+      reportable_impacts.count { |impact| impact.depth == 1 }
+    end
+
+    # @return [Integer] reportable impacts more than one hop away
+    def transitive_count
+      reportable_impacts.length - direct_count
+    end
+
+    # @return [Boolean] true when a global/boot file changed, making any narrow
+    #   answer unreliable
+    def unsafe_focus?
+      diagnostics.any? { |diagnostic| diagnostic.code == "global_file_changed" }
+    end
+
+    # @return [Array<String>] the global files that triggered {#unsafe_focus?}
+    def global_files
+      diagnostics.select { |d| d.code == "global_file_changed" }.map(&:path).compact.uniq.sort
+    end
+
+    # The machine-readable contract. Key order is fixed and every value is a
+    # JSON-native type: no symbols, no absolute paths.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        "schema_version" => SCHEMA_VERSION,
+        "tool" => { "name" => "ripple_effect", "version" => VERSION },
+        "query" => { "type" => query_type.to_s, "value" => query_value },
+        "changed_nodes" => changed_nodes.map(&:to_h),
+        "impacted_nodes" => impacts.map(&:to_h),
+        "tests" => tests.map(&:to_h),
+        "risk" => risk.to_h,
+        "diagnostics" => diagnostics.map(&:to_h),
+        "stats" => stringify(stats)
+      }
+    end
+
+    private
+
+    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
+  end
+end

data/lib/ripple_effect/risk.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  # Turns graph facts into a coarse risk band, and says why.
+  #
+  # A ranking aid for reviewing a change, not a prediction of defects. The formula
+  # is simple and lives in one place so it can be reasoned about and tested. No
+  # percentages: there is no calibrated model behind them.
+  class Risk
+    LEVELS = %i[low medium high critical].freeze
+
+    # Points per fact. Direct dependents count for more than distant ones, and
+    # reachability from an entry point (route, job, callback, mailer) counts
+    # because a request or a queue can trigger it, not just other code.
+    DIRECT_DEPENDENT_POINTS = 1.0
+    TRANSITIVE_DEPENDENT_POINTS = 0.5
+    DIRECT_DEPENDENT_CAP = 8.0
+    TRANSITIVE_DEPENDENT_CAP = 8.0
+
+    ROUTE_POINTS = 2.0
+    JOB_POINTS = 2.0
+    CALLBACK_POINTS = 2.0
+    MAILER_POINTS = 1.0
+    NAMESPACE_CHANGE_POINTS = 3.0
+    GLOBAL_FILE_POINTS = 3.0
+    LAYER_SPREAD_POINTS = 2.0
+
+    LAYER_SPREAD_THRESHOLD = 3
+
+    # Score thresholds, inclusive lower bounds.
+    THRESHOLDS = [[18.0, :critical], [10.0, :high], [4.0, :medium], [0.0, :low]].freeze
+
+    # Path prefixes treated as architectural layers, for the spread heuristic.
+    LAYERS = {
+      "app/controllers/" => "controllers",
+      "app/models/" => "models",
+      "app/services/" => "services",
+      "app/jobs/" => "jobs",
+      "app/mailers/" => "mailers",
+      "app/views/" => "views",
+      "app/channels/" => "channels",
+      "lib/" => "lib"
+    }.freeze
+
+    attr_reader :level, :score, :reasons
+
+    def initialize(level:, score:, reasons:)
+      @level = level
+      @score = score
+      @reasons = reasons.freeze
+      freeze
+    end
+
+    # Scores one change.
+    #
+    # @param impacts [Array<Traversal::Impact>] everything reachable from the change
+    # @param changed_nodes [Array<Node>] what changed
+    # @param global_files [Array<String>] changed paths matching a global/boot glob
+    # @return [Risk]
+    def self.calculate(impacts:, changed_nodes: [], global_files: [])
+      score = 0.0
+      reasons = []
+
+      # File nodes exist so a file-level change can reach the code it declares.
+      # Counting them as dependents would inflate every score by roughly the
+      # number of files touched, which says nothing about actual risk.
+      counted = impacts.reject { |impact| impact.node.kind == :file }
+      direct = counted.count { |impact| impact.depth == 1 }
+      transitive = counted.length - direct
+
+      if direct.positive?
+        score += [direct * DIRECT_DEPENDENT_POINTS, DIRECT_DEPENDENT_CAP].min
+        reasons << "#{direct} direct #{pluralize(direct, 'dependent')}"
+      end
+
+      if transitive.positive?
+        score += [transitive * TRANSITIVE_DEPENDENT_POINTS, TRANSITIVE_DEPENDENT_CAP].min
+        reasons << "#{transitive} transitive #{pluralize(transitive, 'dependent')}"
+      end
+
+      score += score_entry_points(impacts, reasons)
+      score += score_change_shape(changed_nodes, reasons)
+      score += score_global_files(global_files, reasons)
+      score += score_layer_spread(impacts, reasons)
+
+      new(level: level_for(score), score: score.round(2), reasons: reasons)
+    end
+
+    # @return [Symbol] the band for a numeric score
+    def self.level_for(score)
+      THRESHOLDS.find { |threshold, _| score >= threshold }.last
+    end
+
+    # @return [Integer] ordering rank, higher is riskier
+    def self.rank(level)
+      LEVELS.index(level.to_s.to_sym) || 0
+    end
+
+    # @return [Boolean] true when +level+ is at least as risky as +threshold+
+    def at_least?(threshold)
+      self.class.rank(level) >= self.class.rank(threshold)
+    end
+
+    # @return [Hash] JSON-compatible representation
+    def to_h
+      { "level" => level.to_s, "score" => score, "reasons" => reasons }
+    end
+
+    class << self
+      private
+
+      def score_entry_points(impacts, reasons)
+        score = 0.0
+
+        {
+          route: [ROUTE_POINTS, "route"],
+          job: [JOB_POINTS, "background job"],
+          callback: [CALLBACK_POINTS, "model callback"],
+          mailer_action: [MAILER_POINTS, "mailer"]
+        }.each do |kind, (points, label)|
+          count = impacts.count { |impact| impact.node.kind == kind }
+          next if count.zero?
+
+          score += points
+          reasons << "reachable from #{count} #{pluralize(count, label)}"
+        end
+
+        score
+      end
+
+      # Changing a whole class body is broader than changing one method inside it.
+      def score_change_shape(changed_nodes, reasons)
+        return 0.0 unless changed_nodes.any?(&:namespace?)
+
+        reasons << "change touches a class or module body, not just method bodies"
+        NAMESPACE_CHANGE_POINTS
+      end
+
+      def score_global_files(global_files, reasons)
+        return 0.0 if global_files.empty?
+
+        reasons << "changes #{global_files.length} global/boot #{pluralize(global_files.length, 'file')} " \
+                   "(#{global_files.sort.first(3).join(', ')})"
+        GLOBAL_FILE_POINTS
+      end
+
+      # A change confined to one layer is easier to reason about than one that
+      # ripples from models through services into controllers.
+      def score_layer_spread(impacts, reasons)
+        layers = impacts.filter_map { |impact| layer_for(impact.node.path) }.uniq
+        return 0.0 if layers.length < LAYER_SPREAD_THRESHOLD
+
+        reasons << "impact spans #{layers.length} architectural layers (#{layers.sort.join(', ')})"
+        LAYER_SPREAD_POINTS
+      end
+
+      def layer_for(path)
+        LAYERS.each { |prefix, name| return name if path.to_s.start_with?(prefix) }
+        nil
+      end
+
+      def pluralize(count, word)
+        count == 1 ? word : "#{word}s"
+      end
+    end
+  end
+end

data/lib/ripple_effect/static_index/adapter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  # The boundary between Ripple Effect and whichever Ruby indexer backs it.
+  #
+  # Rubydex is young and evolving, so nothing outside this namespace is allowed to
+  # see a Rubydex object. Adapters normalise into the plain value objects defined
+  # here the moment results come back.
+  module StaticIndex
+    # A class, module, or method found in the project.
+    #
+    # @!attribute kind
+    #   @return [Symbol] :class, :module, :instance_method, or :class_method
+    # @!attribute qualified_name
+    #   @return [String] canonical name, e.g. "Commerce::Order#save" or "User.find"
+    Declaration = Struct.new(
+      :kind, :qualified_name, :name, :path, :start_line, :end_line,
+      :owner_name, :superclass_name, :mixins,
+      keyword_init: true
+    ) do
+      # @return [Boolean]
+      def method? = %i[instance_method class_method].include?(kind)
+
+      # @return [Boolean]
+      def namespace? = %i[class module].include?(kind)
+
+      # @return [Array<Hash>] {type: :include|:prepend|:extend, target: String}
+      def mixins = self[:mixins] || []
+    end
+
+    # A call site. +receiver_name+ is set only when the indexer resolved the
+    # receiver to a concrete constant; a nil receiver means we must either infer
+    # the target ourselves at lower confidence, or report it as unresolved.
+    MethodReference = Struct.new(
+      :name, :receiver_name, :path, :line, :enclosing_name,
+      keyword_init: true
+    ) do
+      # @return [Boolean] true when the indexer resolved the receiver
+      def resolved_receiver? = !receiver_name.nil?
+    end
+
+    # A constant mention. +target_name+ is nil when the constant could not be
+    # resolved to an indexed declaration (a gem constant, or a typo).
+    ConstantReference = Struct.new(
+      :name, :target_name, :path, :line, :enclosing_name,
+      keyword_init: true
+    ) do
+      # @return [Boolean]
+      def resolved? = !target_name.nil?
+    end
+
+    # Abstract interface every static index backend must satisfy.
+    #
+    # @abstract
+    class Adapter
+      # Indexes the given absolute paths.
+      # @param paths [Array<String>]
+      # @return [self]
+      def index(paths:) = raise NotImplementedError
+
+      # @return [Array<Declaration>]
+      def declarations = raise NotImplementedError
+
+      # @return [Array<MethodReference>]
+      def method_references = raise NotImplementedError
+
+      # @return [Array<ConstantReference>]
+      def constant_references = raise NotImplementedError
+
+      # @return [Array<Diagnostic>] non-fatal problems encountered while indexing
+      def diagnostics = raise NotImplementedError
+
+      # The innermost declaration containing +line+ in +path+.
+      # @return [Declaration, nil]
+      def declaration_at(path:, line:) = raise NotImplementedError
+
+      # @return [Array<Declaration>] every declaration in +path+
+      def declarations_in(path:) = raise NotImplementedError
+
+      # @return [String] backend name and version, for `doctor` and cache keys
+      def backend_version = raise NotImplementedError
+    end
+  end
+end