testsift 0.0.1

data/lib/testsift/cli/doctor.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module TestSift
+  # Internal CLI — see {TestSift} for the user-facing surface.
+  # @api private
+  module CLI
+    # `testsift doctor` — diagnose config + environment.
+    # Reports Ruby + testsift versions, project root resolution,
+    # cache / coverage / report directory state, and SimpleCov / Rails
+    # presence. Exits 0 on healthy diagnosis, 1 if any check fails.
+    module Doctor
+      # @param args [Array<String>] sub-command args (`-h` / `--help`).
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = healthy, 1 = any check
+      #   FAILed; warnings keep status 0).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.include?('-h') || args.include?('--help')
+
+        checks = [
+          ruby_version_check,
+          tracer_version_check,
+          project_root_check,
+          cache_path_check,
+          coverage_path_check,
+          report_path_check,
+          git_check,
+          simplecov_check,
+          rails_check,
+          cache_schema_version_check,
+          remote_cache_check,
+          ar_schema_narrow_attribution_check,
+          ci_environment_check
+        ]
+        checks.each { |line| stdout.puts line }
+        ok = checks.none? { |line| line.start_with?('FAIL') }
+        ok ? 0 : 1
+      rescue Errno::EPIPE
+        # Downstream pipe (`... | head`) closed early -- routine in
+        # shell pipelines, not a failure. Exit 0 silently.
+        0
+      rescue StandardError => e
+        stderr.puts "doctor: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: testsift doctor
+
+          Diagnose testsift config and environment. Prints a checklist
+          of versions, paths, and integrations; exits 0 if all checks pass.
+        HELP
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.ruby_version_check
+        "OK   ruby:        #{RUBY_DESCRIPTION}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.tracer_version_check
+        "OK   testsift: #{TestSift::VERSION}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.project_root_check
+        "OK   root:        #{TestSift.root}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.cache_path_check
+        path_check('cache_path:', TestSift.cache_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.coverage_path_check
+        path_check('coverage_path:', TestSift.coverage_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.report_path_check
+        path_check('report_path:', TestSift.report_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.path_check(label, path)
+        return "FAIL #{label} <missing>" if path.nil? || path.empty?
+        return "FAIL #{label} #{path} (does not exist)" unless File.directory?(path)
+        return "FAIL #{label} #{path} (not writable)" unless File.writable?(path)
+
+        "OK   #{label} #{path}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.git_check
+        if system('git', 'rev-parse', 'HEAD', out: File::NULL, err: File::NULL)
+          'OK   git:         HEAD reachable (remote_cache will work)'
+        else
+          'WARN git:         not in a git repo (remote_cache will degrade gracefully)'
+        end
+      end
+
+      # `bundle exec testsift doctor` runs in its own process via
+      # the gem's `bin/testsift` binstub, NOT inside the user's
+      # rspec boot — so app code never loads here and a bare
+      # `defined?(::SimpleCov)` check would falsely report "not
+      # loaded" on projects that DO have SimpleCov in their
+      # Gemfile. Probe `Gem.loaded_specs` first to surface the
+      # "installed but not loaded in doctor's process" case
+      # separately from "actually not installed."
+      def self.simplecov_check
+        return 'OK   SimpleCov:   loaded (interop active)' if defined?(::SimpleCov)
+
+        spec = Gem.loaded_specs['simplecov']
+        return "INFO SimpleCov:   installed (v#{spec.version}; not loaded in doctor's process)" if spec
+
+        'INFO SimpleCov:   not installed (this is fine; SimpleCov is optional)'
+      end
+
+      # See {.simplecov_check} for the doctor-runs-in-its-own-
+      # process rationale. Same three-state probe shape: loaded in
+      # this process / installed but not loaded / not installed.
+      def self.rails_check
+        return "OK   Rails:       #{::Rails::VERSION::STRING}" if defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
+
+        spec = Gem.loaded_specs['rails']
+        return "INFO Rails:       installed (v#{spec.version}; not loaded in doctor's process)" if spec
+
+        'INFO Rails:       not installed (this is fine for non-Rails projects)'
+      end
+
+      # Surface a 1.x->2.0 cache mismatch BEFORE the user runs
+      # rspec and watches everything re-run mysteriously. Reads the
+      # cached `last_run.json` (if any) and compares its
+      # `schema_version` against the gem's `Schema::CURRENT`. Three
+      # outcomes: no cache yet (INFO), match (OK), or mismatch (WARN
+      # with the cold-run note). Never FAIL - schema mismatches are
+      # the documented cold-run path, not a hard error.
+      def self.cache_schema_version_check
+        require 'testsift/storage/schema'
+        require 'json'
+
+        cache_path = TestSift.cache_path
+        last_run_path = File.join(cache_path.to_s, 'last_run.json')
+        unless File.file?(last_run_path)
+          return 'INFO schema:      no cache yet (next rspec run is cold; expected on first install)'
+        end
+
+        manifest = JSON.parse(File.read(last_run_path, encoding: 'UTF-8'))
+        stored = manifest['schema_version']
+        current = TestSift::Storage::Schema::CURRENT
+        if stored == current
+          "OK   schema:      v#{current} (matches gem)"
+        else
+          "WARN schema:      stored v#{stored.inspect} != gem v#{current} " \
+            '(next rspec run is a cold run; expected on 1.x->2.0 upgrade)'
+        end
+      rescue StandardError => e
+        "WARN schema:      could not read cache manifest: #{e.class}: #{e.message}"
+      end
+
+      # When remote_cache is configured, verify the backend is
+      # reachable from doctor's vantage point so the user catches
+      # misconfig (typo'd S3 path / unreachable Redis URL / unwritable
+      # local-fs dir) BEFORE the next CI run fails. Best-effort: never
+      # FAIL the gate, just surface a WARN/INFO line.
+      REMOTE_CACHE_PROBES = {
+        s3: ->(opts) { remote_cache_s3_check(opts) },
+        local_fs: ->(opts) { remote_cache_local_fs_check(opts) },
+        redis: ->(opts) { remote_cache_redis_check(opts) }
+      }.freeze
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_check
+        entry = remote_cache_entry
+        return 'INFO remote_cache: not configured (skip)' unless entry
+
+        backend, opts = entry
+        probe = REMOTE_CACHE_PROBES[backend]
+        return "INFO remote_cache: custom backend #{backend.inspect} (skipping reachability probe)" if probe.nil?
+
+        instance_exec(opts, &probe)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_entry
+        return nil unless TestSift.respond_to?(:remote_cache_backend_entry)
+
+        TestSift.remote_cache_backend_entry
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_s3_check(opts)
+        bucket = opts[:bucket] || opts['bucket']
+        return 'WARN remote_cache: :s3 configured without :bucket' if bucket.nil? || bucket.empty?
+
+        "OK   remote_cache: :s3 bucket=#{bucket} " \
+          '(reachability not probed locally; verified end-to-end on next CI run)'
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_local_fs_check(opts)
+        path = opts[:path] || opts['path']
+        return 'WARN remote_cache: :local_fs configured without :path' if path.nil? || path.empty?
+        return "WARN remote_cache: :local_fs path #{path} does not exist" unless File.directory?(path)
+        return "WARN remote_cache: :local_fs path #{path} not writable" unless File.writable?(path)
+
+        "OK   remote_cache: :local_fs path=#{path}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_redis_check(opts)
+        url = opts[:url] || opts['url'] || ENV.fetch('TESTSIFT_REMOTE_CACHE_URI', nil)
+        return 'WARN remote_cache: :redis configured without :url' if url.nil? || url.empty?
+
+        "OK   remote_cache: :redis url=#{url} " \
+          '(reachability not probed locally; verified end-to-end on next CI run)'
+      end
+
+      # Surface the narrow-attribution precondition at diagnostic time.
+      # When `track_ar_schema_notifications` is enabled AND Rails is
+      # loaded AND the rspec-rails default `use_transactional_fixtures
+      # = true` is in effect, per-example BEGIN/COMMIT fires
+      # `sql.active_record` inside the testsift bucket and
+      # attribution silently widens. Same shape as the boot-time warn
+      # in TestSift.start, surfaced here so users running
+      # `testsift doctor` see the issue without having to boot a
+      # full rspec run first.
+      def self.ar_schema_narrow_attribution_check
+        return 'INFO AR schema:   track_ar_schema_notifications not enabled' unless ar_schema_enabled?
+        return 'INFO AR schema:   Rails not loaded' unless rails_loaded?
+
+        if transactional_fixtures_default?
+          'WARN AR schema:   track_ar_schema_notifications + use_transactional_fixtures=true ' \
+            'silently widens to whole-suite-on-schema-change. See README ' \
+            'section "Narrow AR schema attribution".'
+        else
+          'OK   AR schema:   narrow attribution preconditions look good'
+        end
+      end
+
+      # Environment variables that signal a CI environment, one per
+      # major provider plus the near-universal `CI` convention.
+      CI_ENV_VARS = %w[CI GITHUB_ACTIONS GITLAB_CI CIRCLECI BUILDKITE TF_BUILD].freeze
+
+      # Surface the cache-persistence recipes exactly when the user is
+      # on CI, where a non-persisted cache silently degrades every run
+      # to a cold run. Detection requires a var that is set AND
+      # non-empty: `ENV['CI'] == ""` is truthy in Ruby (a shell with
+      # `CI=` exported would otherwise read as detected). INFO both
+      # ways - being in or out of CI is not a health state, so this
+      # check never affects the exit status.
+      def self.ci_environment_check
+        var = CI_ENV_VARS.find { |v| !ENV[v].to_s.empty? }
+        if var
+          "INFO ci:          detected via ENV[#{var}] -- cache persistence recipes: docs/CI_RECIPES.md"
+        else
+          'INFO ci:          not detected (local run)'
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.ar_schema_enabled?
+        return false unless TestSift.respond_to?(:track_ar_schema_notifications?)
+
+        TestSift.track_ar_schema_notifications?
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.rails_loaded?
+        defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.transactional_fixtures_default?
+        return false unless defined?(::RSpec) && ::RSpec.respond_to?(:configuration)
+
+        cfg = ::RSpec.configuration
+        return false unless cfg.respond_to?(:use_transactional_fixtures)
+
+        cfg.use_transactional_fixtures != false
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/testsift/cli/explain.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require 'testsift/cli/snapshot_helpers'
+
+module TestSift
+  # Internal CLI -- see {TestSift} for the user-facing surface.
+  # @api private
+  module CLI
+    # `testsift explain <example>` -- show why a given example is
+    # scheduled to run or skip on the next rspec invocation. Backend-
+    # agnostic: dispatches through {TestSift::Storage::Backend.build}
+    # (via {SnapshotHelpers.load_snapshot}) 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. `--not-run`
+      #   flips the output to the skip-side view: why the example was
+      #   NOT run last time, and what would make it run next time.
+      # @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)
+        args = args.dup
+        not_run = !args.delete('--not-run').nil?
+        return print_help(stdout) if SnapshotHelpers.help_requested?(args)
+
+        loaded = SnapshotHelpers.load_snapshot(TestSift.cache_path, command: 'explain', stderr: stderr)
+        return 1 if loaded.nil?
+
+        snapshot, backend = loaded
+        match = find_example(snapshot.all_examples, args.first)
+        return no_match(args.first, snapshot.all_examples, stderr) if match.nil?
+
+        if not_run
+          print_not_run_explanation(stdout, match, snapshot, backend)
+        else
+          print_explanation(stdout, match, snapshot)
+        end
+        0
+      rescue Errno::EPIPE
+        # Downstream pipe (`... | head`) closed early -- routine in
+        # shell pipelines, not a failure. Exit 0 silently.
+        0
+      rescue StandardError => e
+        stderr.puts "explain: #{e.class}: #{e.message}"
+        1
+      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: testsift explain [--not-run] <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.
+
+          --not-run flips to the skip-side view: whether the example was
+          skipped on the last run (and why no run trigger fired), its last
+          recorded status, and what would make it run on the next rspec
+          invocation. The cache keeps only the most recent snapshot, so
+          "last status" reflects the last run, not a run history.
+        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 = SnapshotHelpers.example_description(meta) || ''
+          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)
+        id = SnapshotHelpers.fetch_meta(meta, 'example_id', 'id')
+        format_lines(meta, skipped: skipped?(id, snapshot)).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, skipped: false)
+        id = SnapshotHelpers.fetch_meta(meta, 'example_id', 'id') || '<unknown>'
+        file, line = SnapshotHelpers.example_location(meta)
+        status = last_status(meta)
+        [
+          "id:           #{id}",
+          "description:  #{SnapshotHelpers.example_description(meta)}",
+          "location:     #{file}:#{line}",
+          "last status:  #{status}",
+          "run reason:   #{run_reason_field(meta, skipped)}"
+        ]
+      end
+
+      # The run-side `run reason:` value. For an example the filter
+      # SKIPPED on the last run, the persisted run_reason is the
+      # carry-forward reason seeded from an earlier snapshot -- it says
+      # why the example ran back then, not why it is in its current
+      # state. Printing it bare would misreport a skipped example as
+      # having a current run trigger, so flag it and point at the
+      # `--not-run` skip-side view instead.
+      # @api private
+      def self.run_reason_field(meta, skipped)
+        reason = SnapshotHelpers.fetch_meta(meta, 'run_reason') || '<not recorded>'
+        return reason unless skipped
+
+        "#{reason} (carried forward from an earlier run; " \
+          'this example was SKIPPED last run -- use --not-run for the skip-side view)'
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.last_status(meta)
+        SnapshotHelpers.dig_meta(meta, 'execution_result', 'status') ||
+          SnapshotHelpers.fetch_meta(meta, 'status') || 'unknown'
+      end
+
+      # The `--not-run` view. Deliberately does NOT print the
+      # `run reason:` field from all_examples meta: for a skipped
+      # example that field is the carry-forward PRIOR-run reason
+      # (seeded from the previous snapshot), so echoing it here would
+      # misreport why the example did not run. Everything below is
+      # derived from the per-run membership sets instead
+      # (skipped_examples / filtered_examples / the status id-sets).
+      def self.print_not_run_explanation(stdout, meta, snapshot, backend)
+        meta = {} unless meta.is_a?(::Hash)
+        id = SnapshotHelpers.fetch_meta(meta, 'example_id', 'id') || '<unknown>'
+        filter_persisted = SnapshotHelpers.filter_decisions_persisted?(backend)
+        print_not_run_header(stdout, meta, id)
+        stdout.puts last_run_line(id, snapshot, filter_persisted: filter_persisted)
+        not_run_detail_lines(id, snapshot).each { |detail| stdout.puts detail }
+        stdout.puts "last status:  #{last_status(meta)} (most recent snapshot; this cache keeps only the last run)"
+        stdout.puts "next run:     #{next_run_line(id, snapshot)}"
+        print_dependency_summary(stdout, meta, snapshot)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_not_run_header(stdout, meta, id)
+        file, line = SnapshotHelpers.example_location(meta)
+        stdout.puts "id:           #{id}"
+        stdout.puts "description:  #{SnapshotHelpers.example_description(meta)}"
+        stdout.puts "location:     #{file}:#{line}"
+      end
+
+      # Detail lines printed under `last run:`: the itemized skip
+      # derivation for a skipped id, a run-side hint for an id that
+      # actually ran, nothing for the no-decision fallbacks.
+      # @return [Array<String>]
+      def self.not_run_detail_lines(id, snapshot)
+        return skip_reason_lines(id, snapshot) if skipped?(id, snapshot)
+
+        return ["  it was not skipped; run 'testsift explain #{id}' for the run-side view"] if ran_reason(id, snapshot)
+
+        []
+      end
+
+      # One `last run:` line for the `--not-run` view, derived from
+      # per-run membership: skipped_examples (the filter skipped it),
+      # filtered_examples (it ran, with the recorded reason), or
+      # neither. The neither case splits on `filter_persisted`: a
+      # backend that persists filter decisions (json) with an empty
+      # decision set means the last run recorded no decision for this
+      # id (a cold run persists empty sets by design, and an id absent
+      # from the last run has no entry either) -- only a
+      # non-persisting backend (sqlite) earns the storage-backend
+      # wording.
+      # @return [String]
+      def self.last_run_line(id, snapshot, filter_persisted:)
+        return 'last run:     skipped (cache hit)' if skipped?(id, snapshot)
+
+        reason = ran_reason(id, snapshot)
+        return "last run:     ran -- #{reason}" if reason
+        return 'last run:     <not recorded by this storage backend>' unless filter_persisted
+
+        'last run:     no filter decision recorded (cold run, or this example was not part of it)'
+      end
+
+      # Itemized derivation of WHY the filter skipped the example.
+      # Sound because a skip logically implies every trigger in the
+      # engine's precedence chain declined: no whole-suite invalidator
+      # fired, no boot file changed (the engine ORs the boot-set check
+      # into whole-suite invalidation), the example carried no
+      # always-re-run status, none of its tracked dependency files
+      # changed, and its tracked environment snapshot was unchanged.
+      # @return [Array<String>]
+      def self.skip_reason_lines(id, snapshot)
+        deps = Array((snapshot.dependency || {})[id])
+        [
+          'skip reason:  no run trigger fired last run:',
+          '  - whole-suite invalidators (Gemfile.lock, .ruby-version, .testsift, gem version): unchanged',
+          '  - boot set: no boot file changed',
+          '  - prior status: not failed / flaky / pending / interrupted',
+          "  - dependency files: #{deps.size} tracked, none changed",
+          '  - environment snapshot: unchanged for this example'
+        ]
+      end
+
+      # Prediction line for the NEXT run, from the persisted status
+      # sets (the inputs to the next run's always-re-run triggers).
+      # @return [String]
+      def self.next_run_line(id, snapshot)
+        reason = always_rerun_reason(id, snapshot)
+        return "will re-run regardless (#{reason} last run)" if reason
+
+        'runs only if a dependency, whole-suite invalidator, boot file, or tracked env var changes'
+      end
+
+      # First always-re-run status the id carries, in the filter's
+      # precedence order (interrupted > flaky > failed > pending), or
+      # nil when the example has no status-based re-run trigger.
+      # @return [String, nil]
+      def self.always_rerun_reason(id, snapshot)
+        return 'interrupted' if in_id_set?(snapshot.interrupted_examples, id)
+        return 'flaky' if in_id_set?(snapshot.flaky_examples, id)
+        return 'failed' if in_id_set?(snapshot.failed_examples, id)
+        return 'pending' if in_id_set?(snapshot.pending_examples, id)
+
+        nil
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.skipped?(id, snapshot)
+        in_id_set?(snapshot.skipped_examples, id)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.ran_reason(id, snapshot)
+        SnapshotHelpers.fetch_meta(snapshot.filtered_examples || {}, id)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.in_id_set?(id_set, id)
+        (id_set || []).include?(id)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_dependency_summary(stdout, meta, snapshot)
+        id = SnapshotHelpers.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/testsift/cli/report_open.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module TestSift
+  # Internal CLI — see {TestSift} for the user-facing surface.
+  # @api private
+  module CLI
+    # `testsift 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')
+
+        report_path = TestSift.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
+
+        launch(opener, index_path, stdout, stderr)
+      rescue Errno::EPIPE
+        # Downstream pipe (`... | head`) closed early -- routine in
+        # shell pipelines, not a failure. Exit 0 silently.
+        0
+      rescue StandardError => e
+        stderr.puts "report:open: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.launch(opener, index_path, stdout, stderr)
+        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
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: testsift 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