ripple_effect 0.1.0

data/lib/ripple_effect/analyzer.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require_relative "graph"
+require_relative "result"
+require_relative "risk"
+require_relative "cache_store"
+require_relative "static_index/rubydex_adapter"
+require_relative "traversal/impact_walker"
+require_relative "diff/git"
+require_relative "diff/changed_symbol_resolver"
+require_relative "extractors/base"
+require_relative "extractors/ruby_structure"
+require_relative "extractors/rails_associations"
+require_relative "extractors/rails_callbacks"
+require_relative "extractors/rails_delegation"
+require_relative "extractors/rails_jobs"
+require_relative "extractors/rails_mailers"
+require_relative "extractors/rails_routes"
+require_relative "extractors/rails_views"
+require_relative "extractors/test_conventions"
+
+module RippleEffect
+  # The public entry point: builds the graph once, then answers questions about it.
+  #
+  # @example
+  #   analyzer = RippleEffect::Analyzer.new(project: RippleEffect::Project.new(root: Dir.pwd))
+  #   result = analyzer.inspect_symbol("BillingService#charge")
+  #   result.risk.level # => :high
+  class Analyzer
+    # Order matters. The structure extractor creates the nodes everything else
+    # attaches to, associations must precede delegation (which resolves targets
+    # through them), and test conventions run last so they can see every node.
+    EXTRACTORS = [
+      Extractors::RubyStructure,
+      Extractors::RailsAssociations,
+      Extractors::RailsCallbacks,
+      Extractors::RailsJobs,
+      Extractors::RailsMailers,
+      Extractors::RailsRoutes,
+      Extractors::RailsDelegation,
+      Extractors::RailsViews,
+      Extractors::TestConventions
+    ].freeze
+
+    attr_reader :project, :diagnostics
+
+    # @param project [Project]
+    # @param cache [Boolean] read and write the on-disk graph cache
+    # @param index [StaticIndex::Adapter, nil] injected in tests
+    def initialize(project:, cache: true, index: nil)
+      @project = project
+      @cache_enabled = cache && project.configuration.cache_enabled
+      @index = index
+      @diagnostics = []
+      @cache_status = "disabled"
+    end
+
+    # Builds (or loads) the graph. Idempotent.
+    #
+    # @return [Graph]
+    def graph
+      @graph ||= build_graph
+    end
+
+    # @return [String] "hit", "miss", or "disabled"
+    def cache_status
+      graph
+      @cache_status
+    end
+
+    # Analyses the blast radius of one symbol.
+    #
+    # @param query [String] e.g. "BillingService#charge", "User", "app/models/user.rb"
+    # @param depth [Integer, nil] maximum hops, nil for unlimited
+    # @param path [String, nil] disambiguates a symbol declared in several files
+    # @param min_confidence [Symbol, nil] overrides the configured floor
+    # @param include_low_confidence [Boolean]
+    # @param direction [Symbol] :dependents, :dependencies, or :both
+    # @return [Result]
+    # @raise [QueryError] when the symbol is unknown or ambiguous
+    def inspect_symbol(query, depth: :default, path: nil, min_confidence: nil,
+                       include_low_confidence: false, direction: :dependents)
+      nodes = resolve_query(query, path: path)
+
+      impacts = walk(
+        nodes.map(&:id),
+        depth: depth, min_confidence: min_confidence,
+        include_low_confidence: include_low_confidence, direction: direction
+      )
+
+      build_result(
+        query_type: :symbol, query_value: query,
+        changed_nodes: nodes, impacts: impacts, global_files: []
+      )
+    end
+
+    # Analyses everything changed between two Git revisions.
+    #
+    # @param base [String] a Git ref
+    # @param head [String, nil] a Git ref, or nil to compare against the working tree
+    # @return [Result]
+    # @raise [GitError] when the repository or refs are unusable
+    def diff(base:, head: nil, depth: :default, min_confidence: nil,
+             include_low_confidence: false)
+      git = Diff::Git.new(root: project.root)
+      changes = git.changed_files(base: base, head: head)
+
+      resolver = Diff::ChangedSymbolResolver.new(project: project, index: index, graph: graph, git: git)
+      changed_nodes = resolver.resolve(changes: changes, base: base, head: head)
+      @diagnostics.concat(resolver.diagnostics)
+
+      impacts = walk(
+        changed_nodes.map(&:id), depth: depth, min_confidence: min_confidence,
+                                 include_low_confidence: include_low_confidence, direction: :dependents
+      )
+
+      global_files = resolver.diagnostics.select { |d| d.code == "global_file_changed" }.map(&:path).compact
+
+      build_result(
+        query_type: :diff,
+        query_value: head ? "#{base}..#{head}" : base,
+        changed_nodes: changed_nodes, impacts: impacts, global_files: global_files
+      )
+    end
+
+    # Health and environment facts for the `doctor` command.
+    #
+    # @return [Hash]
+    def doctor
+      cache = cache_store
+      built = graph
+
+      {
+        "root" => project.root,
+        "rails_like" => project.rails_like?,
+        "ruby_version" => RUBY_VERSION,
+        "ruby_supported" => ruby_supported?,
+        "backend" => StaticIndex::RubydexAdapter.backend_version,
+        "git_repository" => Diff::Git.new(root: project.root).repository?,
+        "config_path" => project.configuration.source_path,
+        "config_warnings" => project.configuration.warnings,
+        "test_framework" => project.test_framework.to_s,
+        "engine_roots" => project.engine_roots,
+        "view_files" => project.view_paths.length,
+        "files_indexed" => project.source_paths.length,
+        "test_files" => project.test_paths.length,
+        "nodes" => built.node_count,
+        "edges" => built.edge_count,
+        "diagnostics" => @diagnostics.length,
+        "cache_enabled" => cache.enabled?,
+        "cache_directory" => cache.directory,
+        "cache_writable" => cache.writable?,
+        "network_access" => false,
+        "boots_application" => false
+      }
+    end
+
+    # Resolves a user query to the node(s) it names.
+    #
+    # @return [Array<Node>]
+    # @raise [QueryError] when nothing matches, or several things do
+    def resolve_query(query, path: nil)
+      text = query.to_s.strip
+      raise QueryError, "empty query" if text.empty?
+
+      # A path query addresses a whole file and its declarations.
+      if text.end_with?(".rb")
+        node = graph.node("file:#{text}")
+        raise QueryError, "no indexed file matches `#{text}`" unless node
+
+        return [node]
+      end
+
+      matches = graph.find_symbol(text)
+      matches = matches.select { |node| node.path == path } if path
+
+      raise QueryError, unknown_symbol_message(text) if matches.empty?
+      return matches if matches.length == 1
+
+      raise QueryError, ambiguous_message(text, matches)
+    end
+
+    private
+
+    def index
+      @index ||= StaticIndex::RubydexAdapter.new(project: project).index(paths: project.source_files)
+    end
+
+    def cache_store
+      @cache_store ||= CacheStore.new(
+        project: project,
+        backend_version: StaticIndex::RubydexAdapter.backend_version,
+        enabled: @cache_enabled
+      )
+    end
+
+    def build_graph
+      store = cache_store
+
+      if store.enabled?
+        cached = store.read
+        @diagnostics.concat(store.diagnostics)
+
+        if cached
+          @cache_status = "hit"
+          # Without this, a warm run reports no limitations at all and therefore
+          # looks more confident than the cold run that produced it.
+          @diagnostics.concat(store.restored_diagnostics)
+          return cached
+        end
+
+        @cache_status = "miss"
+      end
+
+      built = build_graph_from_source
+      store.write(built, @diagnostics) if store.enabled?
+      built
+    end
+
+    def build_graph_from_source
+      graph = Graph.new
+      sources = Extractors::SourceCache.new(project: project)
+      context = Extractors::Context.new(
+        project: project, index: index, graph: graph, sources: sources, diagnostics: @diagnostics
+      )
+
+      EXTRACTORS.each do |extractor_class|
+        feature = extractor_class.feature
+        next if feature && !project.configuration.rails_feature?(feature)
+
+        extractor_class.new(context).extract
+      end
+
+      @diagnostics.concat(index.diagnostics)
+      @diagnostics.concat(sources.diagnostics)
+      warn_if_index_is_empty
+      graph
+    end
+
+    # Indexing many Ruby files and finding no declarations means something
+    # upstream failed silently. Reporting "no impact" there would be wrong, so
+    # this is raised as an error instead.
+    def warn_if_index_is_empty
+      return if project.source_paths.empty?
+      return unless index.declarations.empty?
+
+      @diagnostics << Diagnostic.new(
+        code: "empty_index",
+        severity: :error,
+        message: "indexed #{project.source_paths.length} file(s) but found no Ruby declarations. " \
+                 "Results are not trustworthy. Check that --root points at the project root, " \
+                 "and that `paths.include` matches your layout. An engine monorepo keeps its " \
+                 "code under directories like core/app or engines/*/app."
+      )
+    end
+
+    def walk(ids, depth:, min_confidence:, include_low_confidence:, direction:)
+      floor = min_confidence || effective_min_confidence(include_low_confidence)
+      resolved_depth = depth == :default ? project.configuration.default_depth : depth
+
+      walker = Traversal::ImpactWalker.new(graph: graph, min_confidence: floor)
+
+      case direction
+      when :both
+        forward = walker.walk(ids, depth: resolved_depth, direction: :dependencies)
+        reverse = walker.walk(ids, depth: resolved_depth, direction: :dependents)
+        merge_impacts(reverse, forward)
+      when :dependencies
+        walker.walk(ids, depth: resolved_depth, direction: :dependencies)
+      else
+        walker.walk(ids, depth: resolved_depth, direction: :dependents)
+      end
+    end
+
+    def merge_impacts(primary, secondary)
+      seen = primary.to_h { |impact| [impact.node.id, true] }
+      (primary + secondary.reject { |impact| seen[impact.node.id] })
+        .sort_by { |impact| [impact.depth, impact.node.id] }
+    end
+
+    def effective_min_confidence(include_low_confidence)
+      return Confidence::LOW if include_low_confidence
+
+      project.configuration.min_confidence
+    end
+
+    def build_result(query_type:, query_value:, changed_nodes:, impacts:, global_files:)
+      Result.new(
+        query_type: query_type,
+        query_value: query_value,
+        changed_nodes: changed_nodes,
+        impacts: impacts,
+        tests: rank_tests(impacts, changed_nodes),
+        risk: Risk.calculate(impacts: impacts, changed_nodes: changed_nodes, global_files: global_files),
+        diagnostics: @diagnostics.dup,
+        stats: {
+          # These four keys are part of the documented JSON contract. Project
+          # facts such as discovered engines belong to `doctor`, not here.
+          "files_indexed" => project.source_paths.length,
+          "nodes" => graph.node_count,
+          "edges" => graph.edge_count,
+          "cache" => @cache_status
+        }
+      )
+    end
+
+    # Test files reached by the impact walk, ranked by *why* they were reached.
+    #
+    # A spec that references the changed code outranks one that merely lives at the
+    # conventional path, and a directly-reached spec outranks a distant one.
+    def rank_tests(impacts, changed_nodes)
+      suggestions = {}
+
+      changed_paths = changed_nodes.map(&:path).uniq
+      impacts.each do |impact|
+        next unless impact.node.kind == :test_file
+
+        reason = test_reason(impact)
+        existing = suggestions[impact.node.path]
+        suggestion = TestSuggestion.new(
+          path: impact.node.path, reason: reason, confidence: impact.confidence,
+          depth: impact.depth, evidence: impact.reason&.evidence.to_s
+        )
+
+        suggestions[impact.node.path] = suggestion if existing.nil? || better?(suggestion, existing)
+      end
+
+      # A changed test file is itself worth running.
+      changed_paths.select { |path| project.test_path?(path) }.each do |path|
+        suggestions[path] = TestSuggestion.new(
+          path: path, reason: "reference", confidence: Confidence::HIGH, depth: 0, evidence: "diff.changed_test"
+        )
+      end
+
+      suggestions.values.sort_by { |suggestion| [suggestion.rank, suggestion.depth, suggestion.path] }
+    end
+
+    def test_reason(impact)
+      edge = impact.reason
+      return "heuristic" unless edge
+
+      case edge.evidence
+      when "convention.rspec_path", "convention.minitest_path" then "convention"
+      when "convention.request_spec_path" then "heuristic"
+      when /\Arails\./ then "rails_semantic"
+      else "reference"
+      end
+    end
+
+    def better?(candidate, existing)
+      ([candidate.rank, candidate.depth] <=> [existing.rank, existing.depth]).negative?
+    end
+
+    def ruby_supported?
+      Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2")
+    end
+
+    def unknown_symbol_message(text)
+      suggestions = similar_symbols(text)
+      base = "no indexed symbol matches `#{text}`"
+      suggestions.empty? ? base : "#{base}\nDid you mean: #{suggestions.join(', ')}?"
+    end
+
+    def similar_symbols(text)
+      needle = text.downcase
+      graph.nodes
+           .select { |node| node.qualified_name&.downcase&.include?(needle.split(/[#.]/).first.to_s) }
+           .map(&:qualified_name)
+           .uniq
+           .sort
+           .first(5)
+    end
+
+    def ambiguous_message(text, matches)
+      lines = matches.each_with_index.map { |node, i| "  #{i + 1}. #{node.location}" }
+      "`#{text}` matched #{matches.length} declarations\n#{lines.join("\n")}\nUse --path to disambiguate."
+    end
+  end
+end

data/lib/ripple_effect/cache_store.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "fileutils"
+require_relative "version"
+require_relative "node"
+require_relative "edge"
+require_relative "diagnostic"
+require_relative "graph"
+
+module RippleEffect
+  # Persists a built graph as JSON so a warm run does not re-index the project.
+  #
+  # JSON, never Marshal: a cache file is ordinary data on disk that any process can
+  # write, and Marshal would turn a corrupted cache into arbitrary object
+  # construction. A cache that cannot be read is discarded, never fatal.
+  class CacheStore
+    MANIFEST_FILENAME = "manifest.json"
+    GRAPH_FILENAME = "graph.json"
+
+    attr_reader :directory, :diagnostics
+
+    # @param project [Project]
+    # @param backend_version [String] e.g. "rubydex 0.4.1"
+    # @param enabled [Boolean]
+    def initialize(project:, backend_version:, enabled: true)
+      @project = project
+      @backend_version = backend_version
+      @enabled = enabled
+      @directory = project.cache_directory
+      @diagnostics = []
+      @restored_diagnostics = []
+    end
+
+    # @return [Boolean]
+    def enabled? = @enabled
+
+    # Diagnostics restored alongside the graph on a cache hit.
+    #
+    # @return [Array<Diagnostic>]
+    attr_reader :restored_diagnostics
+
+    # Loads a cached graph, if one exists and is still valid for this project state.
+    #
+    # @return [Graph, nil]
+    def read
+      return nil unless enabled?
+
+      manifest = read_manifest
+      return nil if manifest.nil?
+      return nil unless manifest["key"] == cache_key
+
+      payload = read_json(File.join(directory, GRAPH_FILENAME))
+      return nil if payload.nil?
+
+      deserialize(payload)
+    rescue StandardError => e
+      discard("cache could not be read: #{e.message}")
+      nil
+    end
+
+    # @param graph [Graph]
+    # @param diagnostics [Array<Diagnostic>] stored with the graph, so that a warm
+    #   run reports exactly the same limitations as the cold run that built it
+    # @return [Boolean] true when the cache was written
+    def write(graph, diagnostics = [])
+      return false unless enabled?
+
+      FileUtils.mkdir_p(directory)
+      File.write(File.join(directory, MANIFEST_FILENAME), JSON.pretty_generate(manifest_payload))
+      File.write(File.join(directory, GRAPH_FILENAME), JSON.generate(serialize(graph, diagnostics)))
+      true
+    rescue SystemCallError => e
+      discard("cache could not be written: #{e.message}")
+      false
+    end
+
+    # Whether the cache could be written, without actually creating anything.
+    #
+    # `doctor` asks this. It should not create a directory in the project as a
+    # side effect, least of all when run with `--no-cache`, so check the nearest
+    # existing ancestor instead.
+    #
+    # @return [Boolean]
+    def writable?
+      candidate = directory
+      candidate = File.dirname(candidate) while !File.exist?(candidate) && File.dirname(candidate) != candidate
+
+      File.directory?(candidate) && File.writable?(candidate)
+    rescue SystemCallError
+      false
+    end
+
+    # Removes any cached data.
+    # @return [void]
+    def clear
+      FileUtils.rm_rf(directory)
+    rescue SystemCallError
+      nil
+    end
+
+    # Everything that, if changed, must invalidate the cache: our version, the
+    # cache layout, the indexer, the Ruby running it, the configuration, and the
+    # exact content of every indexed file.
+    #
+    # @return [String] hex SHA-256
+    def cache_key
+      @cache_key ||= begin
+        digest = Digest::SHA256.new
+        digest << VERSION << "\0"
+        digest << CACHE_SCHEMA_VERSION.to_s << "\0"
+        digest << @backend_version << "\0"
+        digest << RUBY_VERSION << "\0"
+        digest << @project.configuration.digest << "\0"
+
+        @project.source_files.each do |path|
+          digest << @project.relative_path(path) << "\0"
+          digest << file_digest(path) << "\0"
+        end
+
+        digest.hexdigest
+      end
+    end
+
+    private
+
+    def file_digest(path)
+      Digest::SHA256.file(path).hexdigest
+    rescue SystemCallError
+      "unreadable"
+    end
+
+    def manifest_payload
+      {
+        "key" => cache_key,
+        "cache_schema_version" => CACHE_SCHEMA_VERSION,
+        "tool_version" => VERSION,
+        "backend" => @backend_version,
+        "ruby_version" => RUBY_VERSION,
+        "files" => @project.source_paths.length
+      }
+    end
+
+    def read_manifest
+      read_json(File.join(directory, MANIFEST_FILENAME))
+    end
+
+    def read_json(path)
+      return nil unless File.file?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError => e
+      discard("cache file #{File.basename(path)} is corrupt: #{e.message}")
+      nil
+    rescue SystemCallError
+      nil
+    end
+
+    def discard(message)
+      @diagnostics << Diagnostic.new(code: "cache_discarded", severity: :info, message: message)
+      clear
+    end
+
+    def serialize(graph, diagnostics)
+      {
+        "nodes" => graph.nodes.map(&:to_h),
+        "edges" => graph.edges.map(&:to_h),
+        "diagnostics" => diagnostics.map(&:to_h)
+      }
+    end
+
+    def deserialize(payload)
+      graph = Graph.new
+
+      Array(payload["nodes"]).each do |raw|
+        graph.add_node(
+          Node.new(
+            id: raw["id"], kind: raw["kind"], name: raw["name"],
+            qualified_name: raw["qualified_name"], path: raw["path"],
+            start_line: raw["start_line"], end_line: raw["end_line"],
+            metadata: raw["metadata"] || {}
+          )
+        )
+      end
+
+      @restored_diagnostics = Array(payload["diagnostics"]).map do |raw|
+        Diagnostic.new(
+          code: raw["code"], message: raw["message"], severity: raw["severity"] || :info,
+          path: raw["path"], line: raw["line"]
+        )
+      end
+
+      Array(payload["edges"]).each do |raw|
+        graph.add_edge(
+          Edge.new(
+            from_id: raw["from_id"], into_id: raw["into_id"], type: raw["type"],
+            evidence: raw["evidence"], confidence: raw["confidence"],
+            location: raw["location"], metadata: raw["metadata"] || {}
+          )
+        )
+      end
+
+      graph
+    end
+  end
+end