ripple_effect 0.1.0

data/lib/ripple_effect/cli/application.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command"
+require_relative "inspect_command"
+require_relative "diff_command"
+require_relative "tests_command"
+require_relative "graph_command"
+require_relative "doctor_command"
+require_relative "version_command"
+
+module RippleEffect
+  module CLI
+    # Parses global flags, dispatches to a subcommand, and owns the process's
+    # exit code. All CLI parsing lives here and in {Command}; no domain object
+    # ever sees an ARGV.
+    class Application
+      COMMANDS = {
+        "inspect" => InspectCommand,
+        "diff" => DiffCommand,
+        "tests" => TestsCommand,
+        "graph" => GraphCommand,
+        "doctor" => DoctorCommand,
+        "version" => VersionCommand
+      }.freeze
+
+      BANNER = <<~BANNER
+        Usage: ripple-effect COMMAND [options]
+
+        Change-impact analysis for Ruby on Rails.
+        Ripple Effect is deterministic and local: it never boots your application,
+        connects to your database, or makes a network call.
+
+        Commands:
+          inspect SYMBOL        What may be affected by changing SYMBOL, and why
+          diff BASE [HEAD]      Blast radius of everything changed between revisions
+          tests BASE [HEAD]     Test files most likely relevant to a change
+          graph SYMBOL          Emit the impacted subgraph as DOT or JSON
+          doctor                Check this project and report what Ripple Effect sees
+          version               Print the version
+
+        Examples:
+          ripple-effect inspect 'BillingService#charge'
+          ripple-effect diff main
+          bundle exec rspec $(ripple-effect tests main)
+          ripple-effect graph 'BillingService#charge' --format dot | dot -Tsvg -o impact.svg
+
+        Global options:
+      BANNER
+
+      def initialize(stdout: $stdout, stderr: $stderr)
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      # @param argv [Array<String>]
+      # @return [Integer] the process exit code
+      def run(argv)
+        options = { format: "text", verbose: false, quiet: false, no_cache: false }
+        rest = parse_global(argv.dup, options)
+
+        return handle_no_command(options) if rest.empty?
+
+        name = rest.shift
+        command_class = COMMANDS[name]
+
+        return unknown_command(name) if command_class.nil?
+
+        command_class.new(options: options, stdout: @stdout, stderr: @stderr).call(rest)
+      rescue OptionParser::ParseError => e
+        @stderr.puts "Error: #{e.message}"
+        @stderr.puts "Run `ripple-effect --help` for usage."
+        Command::USER_ERROR
+      rescue Interrupt
+        @stderr.puts "Interrupted."
+        Command::INTERNAL_ERROR
+      rescue RippleEffect::Error => e
+        @stderr.puts "Error: #{e.message}"
+        Command::INTERNAL_ERROR
+      end
+
+      private
+
+      # Stops at the first non-flag argument so that a subcommand's own flags are
+      # left for the subcommand to parse.
+      def parse_global(argv, options)
+        parser = OptionParser.new do |opts|
+          opts.banner = BANNER
+          opts.on("--root PATH", "Project root (default: current directory)") { |v| options[:root] = v }
+          opts.on("--config PATH", "Path to a .ripple-effect.yml") { |v| options[:config] = v }
+          opts.on("--format FORMAT", %w[text json], "Output format: text (default) or json") do |v|
+            options[:format] = v
+            # `tests` defaults to `paths` rather than `text`, so it needs to know
+            # whether the user actually asked for a format or just got the default.
+            options[:format_given] = true
+          end
+          opts.on("--no-cache", "Ignore and do not write the graph cache") { options[:no_cache] = true }
+          opts.on("--verbose", "Include stats and every diagnostic") { options[:verbose] = true }
+          opts.on("--quiet", "Suppress non-essential output") { options[:quiet] = true }
+          opts.on("-v", "--version", "Print the version") { options[:print_version] = true }
+          opts.on("-h", "--help", "Show this message") { options[:print_help] = true }
+        end
+
+        parser.order(argv)
+      ensure
+        @parser = parser
+      end
+
+      def handle_no_command(options)
+        if options[:print_version]
+          @stdout.puts VERSION
+          return Command::SUCCESS
+        end
+
+        @stdout.puts @parser
+        options[:print_help] ? Command::SUCCESS : Command::USER_ERROR
+      end
+
+      def unknown_command(name)
+        @stderr.puts "Error: unknown command `#{name}`"
+        @stderr.puts "Available commands: #{COMMANDS.keys.join(', ')}"
+        Command::USER_ERROR
+      end
+    end
+  end
+end

data/lib/ripple_effect/cli/command.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../project"
+require_relative "../analyzer"
+require_relative "../formatters/text"
+require_relative "../formatters/json"
+require_relative "../formatters/dot"
+
+module RippleEffect
+  module CLI
+    # Shared behaviour for every subcommand: option parsing, project construction,
+    # and the exit-code contract.
+    #
+    # Exit codes are part of the interface:
+    #   0  success
+    #   1  a threshold the user asked us to enforce was met
+    #   2  a query, configuration, or usage error
+    #   3  an analyzer or internal failure
+    #
+    # @abstract Subclasses implement {#run} and {#banner}.
+    class Command
+      SUCCESS = 0
+      THRESHOLD_MET = 1
+      USER_ERROR = 2
+      INTERNAL_ERROR = 3
+
+      attr_reader :options, :stdout, :stderr
+
+      # @param options [Hash] global options already parsed by {Application}
+      def initialize(options: {}, stdout: $stdout, stderr: $stderr)
+        @options = options
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      # @param argv [Array<String>] arguments after the subcommand name
+      # @return [Integer] the process exit code
+      def call(argv)
+        # `--help` unwinds from inside OptionParser, which has no other way to say
+        # "we are done, successfully".
+        catch(:halt) do
+          rest = parse(argv)
+          run(rest)
+        end
+      rescue OptionParser::ParseError => e
+        report(e, code: USER_ERROR, error_code: "usage")
+      rescue QueryError, ConfigurationError, ProjectError, GitError => e
+        report(e, code: USER_ERROR, error_code: user_error_code(e))
+      rescue IndexError => e
+        report(e, code: INTERNAL_ERROR, error_code: "index_error")
+      end
+
+      # @return [String] the usage banner
+      def banner = raise NotImplementedError
+
+      # @param arguments [Array<String>] positional arguments
+      # @return [Integer] exit code
+      def run(arguments) = raise NotImplementedError
+
+      private
+
+      # Subclasses add their own flags here.
+      def define_options(parser); end
+
+      def parse(argv)
+        parser = OptionParser.new do |opts|
+          opts.banner = banner
+          define_options(opts)
+          define_global_options(opts)
+          opts.on("-h", "--help", "Show this message") do
+            stdout.puts opts
+            throw :halt, SUCCESS
+          end
+        end
+
+        parser.parse(argv)
+      end
+
+      # The global flags are accepted after the subcommand as well as before it.
+      # `ripple-effect inspect Foo --root ../app` is what people actually type, and
+      # rejecting it would be a pointless lesson in argument order.
+      def define_global_options(parser)
+        parser.on("--root PATH", "Project root (default: current directory)") { |v| options[:root] = v }
+        parser.on("--config PATH", "Path to a .ripple-effect.yml") { |v| options[:config] = v }
+        parser.on("--no-cache", "Ignore and do not write the graph cache") { options[:no_cache] = true }
+        parser.on("--verbose", "Include stats and every diagnostic") { options[:verbose] = true }
+        parser.on("--quiet", "Suppress non-essential output") { options[:quiet] = true }
+
+        # `tests` and `graph` define their own --format with different values.
+        return if respond_to?(:custom_format_option?, true) && custom_format_option?
+
+        parser.on("--format FORMAT", %w[text json], "Output format: text (default) or json") do |value|
+          options[:format] = value
+          options[:format_given] = true
+        end
+      end
+
+      # Subclasses that define their own --format override this.
+      def custom_format_option? = false
+
+      def project
+        @project ||= Project.new(root: options[:root] || Dir.pwd, config_path: options[:config])
+      end
+
+      def analyzer
+        @analyzer ||= Analyzer.new(project: project, cache: !options[:no_cache])
+      end
+
+      def json? = options[:format] == "json"
+
+      # Prints a result in whichever format the user asked for.
+      def emit(result)
+        stdout.print(
+          if json?
+            Formatters::Json.new(result: result).render
+          else
+            Formatters::Text.new(result: result, verbose: options[:verbose]).render
+          end
+        )
+      end
+
+      # In JSON mode an error is still JSON, on stderr, so a consumer never has to
+      # parse a human sentence.
+      def report(error, code:, error_code:)
+        if json?
+          stderr.print Formatters::Json.error(error, code: error_code)
+        else
+          stderr.puts "Error: #{error.message}"
+        end
+
+        code
+      end
+
+      def user_error_code(error)
+        case error
+        when QueryError then "query_error"
+        when ConfigurationError then "configuration_error"
+        when GitError then "git_error"
+        else "project_error"
+        end
+      end
+
+      # `--depth 3` / `--depth all`
+      def parse_depth(value)
+        return nil if value.nil? || value == "all"
+
+        depth = Integer(value, exception: false)
+        raise OptionParser::InvalidArgument, "--depth must be a positive integer or \"all\"" if depth.nil? || depth < 1
+
+        depth
+      end
+
+      def parse_confidence(value)
+        return nil if value.nil?
+        unless Confidence.valid?(value)
+          raise OptionParser::InvalidArgument,
+                "--min-confidence must be high, medium, or low"
+        end
+
+        Confidence.cast(value)
+      end
+    end
+  end
+end

data/lib/ripple_effect/cli/diff_command.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module RippleEffect
+  module CLI
+    # `ripple-effect diff BASE [HEAD]`
+    class DiffCommand < Command
+      def banner
+        <<~BANNER
+          Usage: ripple-effect diff BASE [HEAD] [options]
+
+          Show the blast radius of everything changed between two revisions.
+          With only BASE, compares BASE against the working tree, including both
+          staged and unstaged changes.
+
+          Examples:
+            ripple-effect diff main
+            ripple-effect diff origin/main --format json
+            ripple-effect diff v1.2.0 HEAD --fail-on-risk high
+
+          Options:
+        BANNER
+      end
+
+      def run(arguments)
+        base, head = arguments
+
+        if base.nil?
+          stderr.puts "Error: diff requires a BASE revision (e.g. `ripple-effect diff main`)"
+          return USER_ERROR
+        end
+
+        result = analyzer.diff(
+          base: base, head: head,
+          depth: @depth_given ? @depth : :default,
+          min_confidence: @min_confidence,
+          include_low_confidence: @include_low_confidence
+        )
+
+        emit(result)
+        exit_code_for(result)
+      end
+
+      private
+
+      # Analysis finding impact is not a failure. Exiting non-zero happens only
+      # when the user asked us to enforce a threshold.
+      def exit_code_for(result)
+        return SUCCESS unless @fail_on_risk
+        return SUCCESS unless result.risk.at_least?(@fail_on_risk)
+
+        stderr.puts "Risk #{result.risk.level} met the --fail-on-risk #{@fail_on_risk} threshold." unless json?
+
+        THRESHOLD_MET
+      end
+
+      def define_options(parser)
+        parser.on("--depth N", "Maximum hops to follow (integer or \"all\")") do |value|
+          @depth = parse_depth(value)
+          @depth_given = true
+        end
+        parser.on("--min-confidence LEVEL", "Only follow edges at least this confident") do |value|
+          @min_confidence = parse_confidence(value)
+        end
+        parser.on("--include-low-confidence", "Also follow low-confidence edges") do
+          @include_low_confidence = true
+        end
+        parser.on("--fail-on-risk LEVEL", %w[low medium high critical],
+                  "Exit 1 when risk reaches this level") do |value|
+          @fail_on_risk = value.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/ripple_effect/cli/doctor_command.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module RippleEffect
+  module CLI
+    # `ripple-effect doctor`
+    #
+    # Reports what RippleEffect can see and what it will do, including what it
+    # will never do. Makes no network call, here or anywhere else.
+    class DoctorCommand < Command
+      def banner
+        <<~BANNER
+          Usage: ripple-effect doctor [options]
+
+          Check that Ripple Effect can analyse this project, and report what it found.
+
+          Options:
+        BANNER
+      end
+
+      def run(_arguments)
+        report = analyzer.doctor
+
+        if json?
+          stdout.print "#{JSON.pretty_generate(report)}\n"
+          return SUCCESS
+        end
+
+        render(report)
+        report["ruby_supported"] ? SUCCESS : USER_ERROR
+      end
+
+      private
+
+      def render(report)
+        stdout.puts "Ripple Effect #{VERSION}"
+        stdout.puts ""
+
+        section("Project", [
+                  ["root", report["root"]],
+                  ["looks like Rails", yes_no(report["rails_like"])],
+                  ["config", report["config_path"] || "(defaults; no .ripple-effect.yml)"],
+                  ["test framework", report["test_framework"]]
+                ])
+
+        section("Environment", [
+                  ["ruby", ruby_line(report)],
+                  ["static index", report["backend"]],
+                  ["git repository", yes_no(report["git_repository"])]
+                ])
+
+        section("Index", [
+                  ["files indexed", report["files_indexed"]],
+                  ["templates indexed", report["view_files"]],
+                  ["engines discovered", engines_line(report)],
+                  ["test files", report["test_files"]],
+                  ["graph nodes", report["nodes"]],
+                  ["graph edges", report["edges"]],
+                  ["diagnostics", report["diagnostics"]]
+                ])
+
+        section("Cache", [
+                  ["enabled", yes_no(report["cache_enabled"])],
+                  ["directory", report["cache_directory"]],
+                  ["writable", yes_no(report["cache_writable"])]
+                ])
+
+        section("Privacy", [
+                  ["network access", "never"],
+                  ["telemetry", "never"],
+                  ["boots your application", "never"],
+                  ["evaluates your source", "never"]
+                ])
+
+        return if report["config_warnings"].empty?
+
+        stdout.puts "Configuration warnings"
+        report["config_warnings"].each { |warning| stdout.puts "  #{warning}" }
+        stdout.puts ""
+      end
+
+      def section(title, rows)
+        stdout.puts title
+        rows.each { |label, value| stdout.puts "  #{label.to_s.ljust(24)} #{value}" }
+        stdout.puts ""
+      end
+
+      def ruby_line(report)
+        support = report["ruby_supported"] ? "(supported)" : "(unsupported, needs >= 3.2)"
+        "#{report['ruby_version']} #{support}"
+      end
+
+      def engines_line(report)
+        engines = report["engine_roots"]
+        return "none" if engines.empty?
+
+        "#{engines.length} (#{engines.first(4).join(', ')}#{', ...' if engines.length > 4})"
+      end
+
+      def yes_no(value)
+        value ? "yes" : "no"
+      end
+    end
+  end
+end

data/lib/ripple_effect/cli/graph_command.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module RippleEffect
+  module CLI
+    # `ripple-effect graph SYMBOL --format dot`
+    class GraphCommand < Command
+      def banner
+        <<~BANNER
+          Usage: ripple-effect graph SYMBOL [options]
+
+          Emit the impacted subgraph for SYMBOL.
+
+          Examples:
+            ripple-effect graph 'BillingService#charge' --format dot | dot -Tsvg -o impact.svg
+            ripple-effect graph User --format json
+
+          Options:
+        BANNER
+      end
+
+      def run(arguments)
+        symbol = arguments.first
+
+        if symbol.nil?
+          stderr.puts "Error: graph requires a SYMBOL (e.g. 'BillingService#charge')"
+          return USER_ERROR
+        end
+
+        result = analyzer.inspect_symbol(
+          symbol, depth: @depth_given ? @depth : :default, path: @path
+        )
+
+        stdout.print(
+          if options[:format] == "json"
+            Formatters::Json.new(result: result).render
+          else
+            Formatters::Dot.new(result: result).render
+          end
+        )
+
+        SUCCESS
+      end
+
+      private
+
+      # This command defines its own --format with a different set of values.
+      def custom_format_option? = true
+
+      def define_options(parser)
+        parser.on("--format FORMAT", %w[dot json], "dot (default) or json") { |value| options[:format] = value }
+        parser.on("--depth N", "Maximum hops to follow") do |value|
+          @depth = parse_depth(value)
+          @depth_given = true
+        end
+        parser.on("--path PATH", "Disambiguate a symbol declared in several files") { |value| @path = value }
+      end
+    end
+  end
+end

data/lib/ripple_effect/cli/inspect_command.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module RippleEffect
+  module CLI
+    # `ripple-effect inspect SYMBOL`
+    class InspectCommand < Command
+      def banner
+        <<~BANNER
+          Usage: ripple-effect inspect SYMBOL [options]
+
+          Show what may be affected by changing SYMBOL, and why.
+
+          Examples:
+            ripple-effect inspect 'BillingService#charge'
+            ripple-effect inspect User.find --depth 2
+            ripple-effect inspect app/models/order.rb --format json
+
+          Options:
+        BANNER
+      end
+
+      def run(arguments)
+        symbol = arguments.first
+
+        if symbol.nil?
+          stderr.puts "Error: inspect requires a SYMBOL (e.g. 'BillingService#charge')"
+          return USER_ERROR
+        end
+
+        result = analyzer.inspect_symbol(
+          symbol,
+          depth: @depth_given ? @depth : :default,
+          path: @path,
+          min_confidence: @min_confidence,
+          include_low_confidence: @include_low_confidence,
+          direction: @direction || :dependents
+        )
+
+        emit(result)
+        SUCCESS
+      end
+
+      private
+
+      def define_options(parser)
+        parser.on("--depth N", "Maximum hops to follow (integer or \"all\")") do |value|
+          @depth = parse_depth(value)
+          @depth_given = true
+        end
+        parser.on("--path PATH", "Disambiguate a symbol declared in several files") { |value| @path = value }
+        parser.on("--min-confidence LEVEL", "Only follow edges at least this confident") do |value|
+          @min_confidence = parse_confidence(value)
+        end
+        parser.on("--include-low-confidence", "Also follow low-confidence edges") do
+          @include_low_confidence = true
+        end
+        parser.on("--direction DIR", %w[dependents dependencies both],
+                  "dependents (default), dependencies, or both") do |value|
+          @direction = value.to_sym
+        end
+      end
+    end
+  end
+end