rspec-tracer 1.2.2 → 2.0.0.pre.1

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