rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/cli/explain.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'rspec_tracer/storage/backend'
+require 'rspec_tracer/storage/json_backend'
+require 'rspec_tracer/storage/schema'
+require 'rspec_tracer/storage/sqlite_backend' if RUBY_ENGINE == 'ruby'
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer explain <example>` — show why a given example is
+    # scheduled to run or skip on the next rspec invocation. Backend-
+    # agnostic: dispatches through {RSpecTracer::Storage::Backend.build}
+    # so `storage_backend :sqlite` resolves the latest run from the
+    # meta table instead of the JsonBackend-only `last_run.json` file.
+    module Explain
+      # @param args [Array<String>] sub-command args. First positional
+      #   arg is the example_id (or substring) to explain.
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = explanation printed,
+      #   1 = example not found / cache missing).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.empty? || args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+        cache_path = RSpecTracer.cache_path
+
+        snapshot = load_snapshot(cache_path, stderr)
+        return 1 if snapshot.nil?
+
+        match = find_example(snapshot.all_examples, args.first)
+        return no_match(args.first, snapshot.all_examples, stderr) if match.nil?
+
+        print_explanation(stdout, match, snapshot)
+        0
+      rescue StandardError => e
+        stderr.puts "explain: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.load_snapshot(cache_path, stderr)
+        backend = Storage::Backend.build(cache_path: cache_path, configuration: RSpecTracer)
+        run_id = backend.last_run_id
+        if run_id.nil? || run_id.to_s.empty?
+          stderr.puts "explain: no cache yet at #{cache_path} — run rspec first"
+          return nil
+        end
+
+        snapshot = backend.load_graph(schema_version: Storage::Schema::CURRENT)
+        if snapshot.nil?
+          stderr.puts "explain: cache at #{cache_path} is incompatible with this rspec-tracer; next rspec run is cold"
+          return nil
+        end
+
+        snapshot
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.no_match(query, all_examples, stderr)
+        stderr.puts "explain: no example matching #{query.inspect}"
+        stderr.puts "  cache has #{all_examples.size} examples; pass an example_id or substring of description"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: rspec-tracer explain <example_id_or_substring>
+
+          Show why an example is scheduled to run or skip. Matches against
+          example_id exactly first, then falls back to a substring match
+          on the example's full_description. Backend-aware: works under
+          `storage_backend :json` (default) and `storage_backend :sqlite`.
+          Requires a prior rspec run.
+        HELP
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.find_example(all_examples, query)
+        return all_examples[query] if all_examples.key?(query)
+
+        all_examples.find do |id, meta|
+          meta = {} unless meta.is_a?(::Hash)
+          desc = fetch_meta(meta, 'full_description') || fetch_meta(meta, 'description') || ''
+          id.include?(query) || desc.include?(query)
+        end&.last
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_explanation(stdout, meta, snapshot)
+        meta = {} unless meta.is_a?(::Hash)
+        format_lines(meta).each { |line| stdout.puts line }
+        print_dependency_summary(stdout, meta, snapshot)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.format_lines(meta)
+        id = fetch_meta(meta, 'example_id', 'id') || '<unknown>'
+        file = fetch_meta(meta, 'rerun_file_name', 'file_name')
+        line = fetch_meta(meta, 'rerun_line_number', 'line_number')
+        status = dig_meta(meta, 'execution_result', 'status') || fetch_meta(meta, 'status') || 'unknown'
+        [
+          "id:           #{id}",
+          "description:  #{fetch_meta(meta, 'full_description', 'description')}",
+          "location:     #{file}:#{line}",
+          "last status:  #{status}",
+          "run reason:   #{fetch_meta(meta, 'run_reason') || '<not recorded>'}"
+        ]
+      end
+
+      # Look up a key from a Hash, tolerating both String and Symbol
+      # storage. Snapshot Hashes round-tripped through JSON yield
+      # String keys; the post-#182 msgpack serializer preserves
+      # Symbol keys end-to-end, so callers can't assume either shape.
+      def self.fetch_meta(meta, *keys)
+        keys.each do |k|
+          v = meta[k]
+          return v unless v.nil?
+
+          sym_value = meta[k.to_sym]
+          return sym_value unless sym_value.nil?
+        end
+        nil
+      end
+
+      # Look up a nested key from a Hash, tolerating both String and
+      # Symbol storage at each level. See {.fetch_meta} for rationale.
+      def self.dig_meta(meta, *keys)
+        keys.reduce(meta) do |acc, k|
+          break nil if acc.nil? || !acc.is_a?(::Hash)
+
+          acc[k] || acc[k.to_sym]
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_dependency_summary(stdout, meta, snapshot)
+        id = fetch_meta(meta, 'example_id', 'id')
+        deps = snapshot.dependency || {}
+        files = Array(deps[id])
+        stdout.puts "dependencies: #{files.size} files tracked"
+        files.first(10).each { |f| stdout.puts "  - #{f}" }
+        stdout.puts "  ... (#{files.size - 10} more)" if files.size > 10
+      end
+    end
+  end
+end

data/lib/rspec_tracer/cli/report_open.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer report:open` — open the HTML report in the default
+    # browser. Resolves `report_path/index.html` and dispatches via
+    # `open` (macOS) / `xdg-open` (Linux). Falls back to printing the
+    # path when no opener is available.
+    module ReportOpen
+      # @param args [Array<String>] sub-command args (`-h` / `--help`).
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = opened or path printed,
+      #   1 = report missing).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+
+        report_path = RSpecTracer.report_path
+        index_path = File.join(report_path, 'index.html')
+
+        unless File.file?(index_path)
+          stderr.puts "report:open: no report at #{index_path}"
+          stderr.puts '  run rspec first to generate the HTML report'
+          return 1
+        end
+
+        opener = detect_opener
+        if opener.nil?
+          stdout.puts "report:open: report at #{index_path}"
+          stdout.puts '  no opener detected (open / xdg-open); open the path manually'
+          return 0
+        end
+
+        if system(opener, index_path, out: File::NULL, err: File::NULL)
+          stdout.puts "report:open: opened #{index_path} via #{opener}"
+          0
+        else
+          stderr.puts "report:open: failed to launch #{opener} #{index_path}"
+          1
+        end
+      rescue StandardError => e
+        stderr.puts "report:open: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: rspec-tracer report:open
+
+          Open the HTML report (`report_path/index.html`) in the default
+          browser. Uses `open` on macOS and `xdg-open` on Linux. Prints
+          the path and exits 0 when no opener is available.
+        HELP
+        0
+      end
+
+      # Returns the opener binary name on PATH, or nil. Checked in
+      # priority order: macOS `open`, then Linux `xdg-open`. Windows
+      # is unsupported per `COMPATIBILITY_MATRIX.md`'s explicit drop;
+      # users on Windows see the print-the-path fallback.
+      def self.detect_opener
+        %w[open xdg-open].find { |bin| which(bin) }
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.which(binary)
+        found = ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+          path = File.join(dir, binary)
+          File.file?(path) && File.executable?(path)
+        end
+        found ? binary : nil
+      end
+    end
+  end
+end

data/lib/rspec_tracer/cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+# Require the top-level entry to pull in `docile` (used by
+# `Configuration#configure`) plus the autoloads sub-commands rely on.
+# Loading `rspec_tracer` does NOT call `RSpecTracer.start` - the engine
+# stays inert until a user invokes it explicitly.
+require 'rspec_tracer'
+
+module RSpecTracer
+  # Command-line entry for the `rspec-tracer` binary. Five sub-commands
+  # per USER_FACING_SURFACE.md §10: `doctor`, `cache:info`, `cache:clear`,
+  # `report:open`, `explain <example>`.
+  #
+  # The CLI is opt-in — the canonical CI flow continues to go through
+  # `rake rspec_tracer:remote_cache:*` tasks per USER_FACING_SURFACE.md
+  # §5. Sub-commands operate against the local cache + report
+  # directories resolved from the project's `.rspec-tracer` config
+  # (loaded lazily on first sub-command dispatch, not at CLI load time —
+  # `doctor` deliberately runs without requiring a configured project).
+  #
+  # @api private
+  module CLI
+    # Internal constant.
+    # @api private
+    SUB_COMMANDS = {
+      'doctor' => 'Doctor',
+      'cache:info' => 'CacheInfo',
+      'cache:clear' => 'CacheClear',
+      'report:open' => 'ReportOpen',
+      'explain' => 'Explain'
+    }.freeze
+
+    # CLI entry. Called by `bin/rspec-tracer` with `ARGV`. Wraps every
+    # sub-command in a top-level rescue so the binary always exits
+    # with a meaningful integer status (0 / 1) instead of a backtrace.
+    #
+    # @param argv [Array<String>] command-line arguments (excluding
+    #   the program name)
+    # @param stdout [IO] stream for normal output (default `$stdout`)
+    # @param stderr [IO] stream for errors / diagnostics (default `$stderr`)
+    # @return [Integer] exit status (0 = success, 1 = failure)
+    def self.run(argv, stdout: $stdout, stderr: $stderr)
+      args = argv.dup
+      return print_top_level_help(stdout) if args.empty? || %w[-h --help help].include?(args.first)
+      return print_version(stdout) if %w[-v --version].include?(args.first)
+
+      dispatch(args, stdout: stdout, stderr: stderr)
+    rescue StandardError => e
+      stderr.puts "rspec-tracer: #{e.class}: #{e.message}"
+      1
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.dispatch(args, stdout:, stderr:)
+      sub = args.shift
+      klass_name = SUB_COMMANDS[sub]
+      return unknown_sub_command(sub, stderr) if klass_name.nil?
+
+      load_sub_command(klass_name)
+      RSpecTracer::CLI.const_get(klass_name).run(args, stdout: stdout, stderr: stderr)
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.unknown_sub_command(sub, stderr)
+      stderr.puts "rspec-tracer: unknown sub-command #{sub.inspect}"
+      stderr.puts "  available: #{SUB_COMMANDS.keys.join(', ')}"
+      1
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.print_top_level_help(stdout)
+      stdout.puts <<~HELP
+        Usage: rspec-tracer <sub-command> [options]
+
+        Sub-commands:
+          doctor          Diagnose rspec-tracer config + environment.
+          cache:info      Show cache size, last run timestamp, and example counts.
+          cache:clear     Remove cache, coverage, and report directories.
+          report:open     Open the HTML report in the default browser.
+          explain <id>    Show why an example is scheduled to run or skip.
+
+        Options:
+          -h, --help      Print this help message.
+          -v, --version   Print rspec-tracer version.
+
+        Run `rspec-tracer <sub-command> --help` for sub-command options.
+      HELP
+      0
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.print_version(stdout)
+      stdout.puts "rspec-tracer #{RSpecTracer::VERSION}"
+      0
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.load_sub_command(klass_name)
+      filename = klass_name.gsub(/([A-Z])/) { |m| "_#{m.downcase}" }.sub(/^_/, '')
+      require_relative "cli/#{filename}"
+    rescue LoadError => e
+      # LoadError isn't a StandardError, so the outer `rescue StandardError`
+      # in `.run` wouldn't catch it. Re-raise as StandardError so the dispatch
+      # path stays uniform: any sub-command resolution failure prints
+      # `rspec-tracer: <class>: <message>` and exits 1.
+      raise StandardError, "could not load sub-command #{klass_name.inspect}: #{e.message}"
+    end
+  end
+end