ripple_effect 0.1.0

data/lib/ripple_effect/cli/tests_command.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module RippleEffect
+  module CLI
+    # `ripple-effect tests BASE [HEAD]`
+    #
+    # The `paths` format prints nothing but test paths on stdout so it composes:
+    #
+    #   bundle exec rspec $(ripple-effect tests main)
+    #
+    # Every warning therefore goes to stderr. When a global or boot-impact file
+    # changed, a narrow list would be actively misleading, so the command refuses
+    # to print one unless the user overrides with --allow-unsafe-focus. Ripple Effect
+    # recommends tests; it never claims the rest are unnecessary.
+    class TestsCommand < Command
+      def banner
+        <<~BANNER
+          Usage: ripple-effect tests BASE [HEAD] [options]
+
+          Print the test files most likely to be relevant to a change.
+
+          Examples:
+            bundle exec rspec $(ripple-effect tests main)
+            ripple-effect tests origin/main --format json
+
+          Options:
+        BANNER
+      end
+
+      def run(arguments)
+        base, head = arguments
+
+        if base.nil?
+          stderr.puts "Error: tests requires a BASE revision (e.g. `ripple-effect tests main`)"
+          return USER_ERROR
+        end
+
+        result = analyzer.diff(base: base, head: head, min_confidence: @min_confidence)
+
+        return refuse(result) if result.unsafe_focus? && !@allow_unsafe_focus
+
+        emit_tests(result)
+        SUCCESS
+      end
+
+      private
+
+      def refuse(result)
+        stderr.puts "WARNING: focused tests may be incomplete because " \
+                    "#{result.global_files.join(', ')} changed."
+        stderr.puts "These files affect application boot or configuration, so the impact graph " \
+                    "cannot bound what they reach."
+        stderr.puts "Run your full suite, or pass --allow-unsafe-focus to print a narrowed list anyway."
+
+        if json?
+          stderr.print Formatters::Json.error(
+            RippleEffect::Error.new("unsafe focus: #{result.global_files.join(', ')} changed"),
+            code: "unsafe_focus"
+          )
+        end
+
+        USER_ERROR
+      end
+
+      def emit_tests(result)
+        case effective_format
+        when "json" then stdout.print Formatters::Json.new(result: result).render
+        when "text" then stdout.print Formatters::Text.new(result: result, verbose: options[:verbose]).render
+        else
+          warn_if_empty(result)
+          result.test_files.each { |path| stdout.puts path }
+        end
+      end
+
+      # Unlike every other command, this one defaults to bare paths so that
+      # `bundle exec rspec $(ripple-effect tests main)` works without flags.
+      def effective_format
+        options[:format_given] ? options[:format] : "paths"
+      end
+
+      def warn_if_empty(result)
+        return unless result.test_files.empty?
+
+        stderr.puts "No relevant test files found for #{result.query_value}. Run your full suite."
+      end
+
+      # This command defines its own --format with a different set of values.
+      def custom_format_option? = true
+
+      def define_options(parser)
+        parser.on("--runner RUNNER", %w[rspec minitest auto], "Test framework (default: auto)") do |value|
+          @runner = value.to_sym
+        end
+        parser.on("--allow-unsafe-focus", "Print a narrowed list even when a global file changed") do
+          @allow_unsafe_focus = true
+        end
+        parser.on("--min-confidence LEVEL", "Only follow edges at least this confident") do |value|
+          @min_confidence = parse_confidence(value)
+        end
+        parser.on("--format FORMAT", %w[paths text json], "paths (default), text, or json") do |value|
+          options[:format] = value
+          options[:format_given] = true
+        end
+      end
+    end
+  end
+end

data/lib/ripple_effect/cli/version_command.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module RippleEffect
+  module CLI
+    # `ripple-effect version`
+    #
+    # Prints the bare semantic version, so it can be captured in a shell variable
+    # without post-processing. `--verbose` adds environment details.
+    class VersionCommand < Command
+      def banner
+        <<~BANNER
+          Usage: ripple-effect version [options]
+
+          Print the Ripple Effect version.
+
+          Options:
+        BANNER
+      end
+
+      def run(_arguments)
+        if json?
+          stdout.print "#{JSON.pretty_generate(payload)}\n"
+        elsif options[:verbose]
+          payload.each { |key, value| stdout.puts "#{key}: #{value}" }
+        else
+          stdout.puts VERSION
+        end
+
+        SUCCESS
+      end
+
+      private
+
+      def payload
+        {
+          "ripple_effect" => VERSION,
+          "schema_version" => SCHEMA_VERSION,
+          "ruby" => RUBY_VERSION,
+          "static_index" => StaticIndex::RubydexAdapter.backend_version
+        }
+      end
+    end
+  end
+end

data/lib/ripple_effect/confidence.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  # Confidence bands for graph edges.
+  #
+  # Three coarse bands rather than a numeric probability. Ruby is dynamic enough
+  # that a percentage would be false precision. The numeric +RANK+ is only used
+  # for ranking and traversal.
+  #
+  # - +:high+   explicit static reference, or a literal Rails DSL relationship
+  # - +:medium+ receiver or target inferred from a strong convention
+  # - +:low+    naming or path heuristic only
+  module Confidence
+    HIGH = :high
+    MEDIUM = :medium
+    LOW = :low
+
+    # Ordered from strongest to weakest.
+    ALL = [HIGH, MEDIUM, LOW].freeze
+
+    RANK = { HIGH => 3, MEDIUM => 2, LOW => 1 }.freeze
+
+    module_function
+
+    # @param value [Symbol, String]
+    # @return [Symbol] the canonical band
+    # @raise [ArgumentError] when the value is not a known band
+    def cast(value)
+      band = value.to_s.downcase.to_sym
+      return band if ALL.include?(band)
+
+      raise ArgumentError, "unknown confidence #{value.inspect}, expected one of #{ALL.join(', ')}"
+    end
+
+    # @return [Boolean] true when +value+ is a known band
+    def valid?(value)
+      ALL.include?(value.to_s.downcase.to_sym)
+    end
+
+    # @return [Integer] numeric rank, higher is more confident
+    def rank(value)
+      RANK.fetch(cast(value))
+    end
+
+    # @return [Boolean] true when +value+ is at least as confident as +minimum+
+    def at_least?(value, minimum)
+      rank(value) >= rank(minimum)
+    end
+
+    # The weakest of the given bands, which is how a path's confidence is derived:
+    # a chain of reasoning is only as trustworthy as its weakest link.
+    #
+    # @param bands [Array<Symbol>]
+    # @return [Symbol]
+    def weakest(bands)
+      return HIGH if bands.empty?
+
+      bands.min_by { |band| rank(band) }
+    end
+  end
+end

data/lib/ripple_effect/configuration.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "digest"
+require_relative "error"
+require_relative "confidence"
+
+module RippleEffect
+  # Merged view of the built-in defaults and the project's `.ripple-effect.yml`.
+  #
+  # Unknown top-level keys produce a warning ({#warnings}) rather than silence,
+  # while invalid values for a known key are a hard {ConfigurationError}: a typo in
+  # a key is usually harmless, but a bad value would silently change what we analyse.
+  class Configuration
+    CONFIG_FILENAME = ".ripple-effect.yml"
+    SCHEMA_VERSION = 1
+
+    DEFAULT_INCLUDE = [
+      "app/**/*.rb",
+      "lib/**/*.rb",
+      "config/routes.rb",
+      "config/routes/**/*.rb",
+      "spec/**/*.rb",
+      "test/**/*.rb"
+    ].freeze
+
+    # Templates are not Ruby files, so they need their own patterns. In a classic
+    # server-rendered Rails application the views are a large part of the real
+    # dependency graph, and leaving them out understates every helper's blast
+    # radius.
+    DEFAULT_VIEW_INCLUDE = [
+      "app/views/**/*.erb"
+    ].freeze
+
+    DEFAULT_EXCLUDE = [
+      "vendor/**",
+      "node_modules/**",
+      "tmp/**",
+      "log/**",
+      "coverage/**",
+      "public/assets/**",
+      "storage/**",
+      ".bundle/**",
+      ".git/**"
+    ].freeze
+
+    # Files whose change can affect nearly anything, so a narrow answer would be
+    # misleading. See {Analyzer} and the `tests` command's refusal behaviour.
+    DEFAULT_GLOBAL_FILES = [
+      "Gemfile",
+      "Gemfile.lock",
+      "config/application.rb",
+      "config/environment.rb",
+      "config/boot.rb",
+      "config/environments/**",
+      "config/initializers/**",
+      "config/routes.rb",
+      "spec/spec_helper.rb",
+      "spec/rails_helper.rb",
+      "test/test_helper.rb"
+    ].freeze
+
+    RAILS_EXTRACTORS = %i[routes associations callbacks jobs mailers delegation views].freeze
+    TEST_FRAMEWORKS = %i[auto rspec minitest].freeze
+    KNOWN_SECTIONS = %w[version paths analysis rails tests cache].freeze
+
+    attr_reader :include_patterns, :view_patterns, :exclude_patterns,
+                :discover_engines, :min_confidence, :default_depth,
+                :include_low_confidence, :rails_features, :test_framework,
+                :unsafe_global_files, :cache_enabled, :cache_directory, :warnings, :source_path
+
+    # @param settings [Hash] raw settings, normally from YAML
+    # @param source_path [String, nil] where the settings came from, for messages
+    def initialize(settings = {}, source_path: nil)
+      @warnings = []
+      @source_path = source_path
+      settings = stringify(settings || {})
+
+      validate_sections!(settings)
+
+      paths = section(settings, "paths")
+      analysis = section(settings, "analysis")
+      rails = section(settings, "rails")
+      tests = section(settings, "tests")
+      cache = section(settings, "cache")
+
+      @include_patterns = string_list(paths, "include", DEFAULT_INCLUDE)
+      @view_patterns = string_list(paths, "views", DEFAULT_VIEW_INCLUDE)
+      @exclude_patterns = string_list(paths, "exclude", DEFAULT_EXCLUDE)
+      @discover_engines = boolean(paths, "discover_engines", true)
+
+      @min_confidence = confidence_value(analysis, "min_confidence", Confidence::MEDIUM)
+      @default_depth = depth_value(analysis["default_depth"])
+      @include_low_confidence = boolean(analysis, "include_low_confidence", false)
+
+      @rails_features = RAILS_EXTRACTORS.to_h { |name| [name, boolean(rails, name.to_s, true)] }.freeze
+
+      @test_framework = enum_value(tests, "framework", TEST_FRAMEWORKS, :auto)
+      @unsafe_global_files = string_list(tests, "unsafe_global_files", DEFAULT_GLOBAL_FILES)
+
+      @cache_enabled = boolean(cache, "enabled", true)
+      @cache_directory = (cache["directory"] || "tmp/ripple_effect").to_s
+
+      @warnings.freeze
+    end
+
+    # Loads `.ripple-effect.yml` from +root+, or an explicit +path+.
+    #
+    # @param root [String] project root
+    # @param path [String, nil] explicit config path; must exist when given
+    # @return [Configuration] defaults when no config file is present
+    # @raise [ConfigurationError] when the file is unreadable, malformed, or an
+    #   explicitly requested path is missing
+    def self.load(root:, path: nil)
+      config_path = path ? File.expand_path(path, root) : File.join(root, CONFIG_FILENAME)
+
+      unless File.file?(config_path)
+        raise ConfigurationError, "config file not found: #{config_path}" if path
+
+        return new({}, source_path: nil)
+      end
+
+      new(parse(config_path), source_path: config_path)
+    end
+
+    # Parses a YAML config file safely: no aliases, no object deserialisation.
+    #
+    # @return [Hash]
+    def self.parse(config_path)
+      raw = YAML.safe_load_file(config_path, permitted_classes: [], aliases: false)
+      raise ConfigurationError, "config file #{config_path} must contain a YAML mapping" unless raw.is_a?(Hash)
+
+      version = raw["version"]
+      raise ConfigurationError, "config file #{config_path} must declare `version: #{SCHEMA_VERSION}`" if version.nil?
+
+      unless version == SCHEMA_VERSION
+        raise ConfigurationError,
+              "unsupported config version #{version.inspect} in #{config_path}, expected #{SCHEMA_VERSION}"
+      end
+
+      raw
+    rescue Psych::Exception => e
+      raise ConfigurationError, "could not parse #{config_path}: #{e.message}"
+    end
+
+    # @param feature [Symbol] one of {RAILS_EXTRACTORS}
+    # @return [Boolean]
+    def rails_feature?(feature)
+      @rails_features.fetch(feature, false)
+    end
+
+    # The effective confidence floor for traversal: low-confidence edges are
+    # excluded unless the user opts in.
+    #
+    # @return [Symbol]
+    def effective_min_confidence
+      return Confidence::LOW if include_low_confidence
+
+      min_confidence
+    end
+
+    # A digest of everything that affects analysis output, used as part of the
+    # cache key so a config change invalidates the cache.
+    #
+    # @return [String] hex SHA-256
+    def digest
+      Digest::SHA256.hexdigest(to_h.inspect)
+    end
+
+    # @return [Hash] the fully resolved settings
+    def to_h
+      {
+        "version" => SCHEMA_VERSION,
+        "paths" => {
+          "include" => include_patterns, "views" => view_patterns,
+          "exclude" => exclude_patterns, "discover_engines" => discover_engines
+        },
+        "analysis" => {
+          "min_confidence" => min_confidence.to_s,
+          "default_depth" => default_depth,
+          "include_low_confidence" => include_low_confidence
+        },
+        "rails" => rails_features.transform_keys(&:to_s),
+        "tests" => { "framework" => test_framework.to_s, "unsafe_global_files" => unsafe_global_files },
+        "cache" => { "enabled" => cache_enabled, "directory" => cache_directory }
+      }
+    end
+
+    private
+
+    def validate_sections!(settings)
+      unknown = settings.keys - KNOWN_SECTIONS
+      return if unknown.empty?
+
+      @warnings << "unknown configuration key(s): #{unknown.sort.join(', ')}"
+    end
+
+    def section(settings, name)
+      value = settings[name]
+      return {} if value.nil?
+      raise ConfigurationError, "`#{name}` must be a mapping" unless value.is_a?(Hash)
+
+      value
+    end
+
+    def string_list(source, key, default)
+      value = source[key]
+      return default.dup if value.nil?
+      raise ConfigurationError, "`#{key}` must be a list of strings" unless value.is_a?(Array)
+
+      value.map do |entry|
+        raise ConfigurationError, "`#{key}` must be a list of strings" unless entry.is_a?(String)
+
+        normalize_glob(entry)
+      end
+    end
+
+    # Strips a leading "./" so patterns compare cleanly against project-relative paths.
+    def normalize_glob(pattern)
+      pattern.strip.sub(%r{\A\./}, "")
+    end
+
+    def boolean(source, key, default)
+      value = source[key]
+      return default if value.nil?
+      return value if [true, false].include?(value)
+
+      raise ConfigurationError, "`#{key}` must be true or false, got #{value.inspect}"
+    end
+
+    def confidence_value(source, key, default)
+      value = source[key]
+      return default if value.nil?
+      unless Confidence.valid?(value)
+        raise ConfigurationError,
+              "`#{key}` must be one of #{Confidence::ALL.join(', ')}, got #{value.inspect}"
+      end
+
+      Confidence.cast(value)
+    end
+
+    def enum_value(source, key, allowed, default)
+      value = source[key]
+      return default if value.nil?
+
+      symbol = value.to_s.to_sym
+      return symbol if allowed.include?(symbol)
+
+      raise ConfigurationError, "`#{key}` must be one of #{allowed.join(', ')}, got #{value.inspect}"
+    end
+
+    # `all` and nil both mean unlimited depth; anything else must be a positive integer.
+    def depth_value(value)
+      return nil if value.nil? || value.to_s == "all"
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ConfigurationError, "`default_depth` must be a positive integer or \"all\", got #{value.inspect}"
+    end
+
+    def stringify(hash)
+      hash.to_h { |key, value| [key.to_s, value.is_a?(Hash) ? stringify(value) : value] }
+    end
+  end
+end

data/lib/ripple_effect/diagnostic.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RippleEffect
+  # A non-fatal fact about the analysis: something we could not resolve, skipped,
+  # or want the user to know limits the answer.
+  #
+  # Diagnostics carry a stable +code+ so tooling can match on it rather than on
+  # message text, which is free to change.
+  class Diagnostic
+    SEVERITIES = %i[info warning error].freeze
+
+    # Stable diagnostic codes emitted by v0.1.
+    CODES = %w[
+      unresolved_polymorphic_association
+      unresolved_association_target
+      unresolved_delegate_target
+      unresolved_method_receiver
+      unresolved_route_controller
+      unparsed_file
+      unmapped_changed_lines
+      global_file_changed
+      deleted_file
+      renamed_file
+      cache_discarded
+      dynamic_dispatch
+      empty_index
+      index_note
+    ].freeze
+
+    attr_reader :severity, :code, :message, :path, :line
+
+    # @param code [String] one of {CODES}, or a new stable code
+    # @param message [String] human explanation
+    # @param severity [Symbol] one of {SEVERITIES}
+    # @param path [String, nil] project-relative path
+    # @param line [Integer, nil]
+    def initialize(code:, message:, severity: :warning, path: nil, line: nil)
+      @severity = self.class.cast_severity(severity)
+      @code = code.to_s.freeze
+      @message = message.to_s.freeze
+      @path = path&.to_s&.freeze
+      @line = line
+      freeze
+    end
+
+    # @return [Symbol]
+    # @raise [ArgumentError] on an unknown severity
+    def self.cast_severity(severity)
+      symbol = severity.to_s.to_sym
+      return symbol if SEVERITIES.include?(symbol)
+
+      raise ArgumentError, "unknown diagnostic severity #{severity.inspect}"
+    end
+
+    # @return [String] identity used to deduplicate repeated diagnostics
+    def key
+      "#{code}|#{path}|#{line}|#{message}"
+    end
+
+    # @return [Hash] JSON-compatible representation with deterministic key order
+    def to_h
+      {
+        "severity" => severity.to_s,
+        "code" => code,
+        "path" => path,
+        "line" => line,
+        "message" => message
+      }
+    end
+
+    # @return [String] "warning: message (path:line)"
+    def to_s
+      suffix = if path
+                 " (#{line ? "#{path}:#{line}" : path})"
+               else
+                 ""
+               end
+      "#{severity}: #{message}#{suffix}"
+    end
+
+    def ==(other)
+      other.is_a?(Diagnostic) && other.key == key
+    end
+    alias eql? ==
+
+    def hash
+      key.hash
+    end
+  end
+end