rspec-tracer 1.2.3 → 2.0.0.pre.2

data/bin/rspec-tracer

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Entry point for the `rspec-tracer` CLI. The binary is opt-in for
+# users who want diagnostics, cache inspection, or report-opening
+# from the command line; the canonical CI flow continues to go
+# through `rake rspec_tracer:remote_cache:*` tasks per
+# USER_FACING_SURFACE.md §5.
+
+lib_dir = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require 'rspec_tracer/cli'
+
+exit RSpecTracer::CLI.run(ARGV)

data/lib/rspec_tracer/cache/Rakefile

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# User-facing Rake task shim for local-cache maintenance. Load from
+# the user's own Rakefile when they want one-off cleanup:
+#
+#   spec = Gem::Specification.find_by_name('rspec-tracer')
+#   load "#{spec.gem_dir}/lib/rspec_tracer/cache/Rakefile"
+#
+# Defines `rspec_tracer:cache:gc` which prunes old run-id
+# directories under the local cache while retaining the `N`
+# most-recent configured via `cache_retention_local_count` (default
+# 5). Prune-on-save already handles the steady-state cleanup; this
+# task is for catching up after retention was opted-out-of and the
+# cache grew beyond the configured cap.
+
+require 'rspec_tracer'
+require 'rspec_tracer/storage/json_backend'
+
+namespace :rspec_tracer do
+  namespace :cache do
+    desc 'Prune old run-id directories under the local cache ' \
+         '(respects cache_retention_local_count)'
+    task :gc do
+      count = RSpecTracer.cache_retention_local_count
+      if count.nil? || count.zero?
+        RSpecTracer.logger.warn(
+          'rspec-tracer cache gc: cache_retention_local_count is 0 (opt-out); nothing to prune'
+        )
+        next
+      end
+
+      backend = RSpecTracer::Storage::JsonBackend.new(
+        cache_path: RSpecTracer.cache_path,
+        logger: RSpecTracer.logger,
+        retention_local_count: count
+      )
+      removed = backend.prune_run_dirs!(keep: count)
+      RSpecTracer.logger.info(
+        "rspec-tracer cache gc: pruned #{removed} run-id dir(s); kept #{count} most-recent"
+      )
+    end
+  end
+end

data/lib/rspec_tracer/cli/cache_clear.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer cache:clear` — remove cache, coverage, and report
+    # directories. Prompts for confirmation unless `--yes` is passed.
+    # The next rspec run is a cold run.
+    module CacheClear
+      # @param args [Array<String>] sub-command args (`-y` / `--yes`
+      #   skips confirmation; `-h` / `--help` prints help).
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = success / aborted, 1 = error).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+        existing = existing_targets
+        return nothing_to_remove(stdout) if existing.empty?
+
+        announce(stdout, existing)
+        return aborted(stdout) unless skip_confirmation?(args) || confirm?(stdout)
+
+        remove_each(stdout, existing)
+        0
+      rescue StandardError => e
+        stderr.puts "cache:clear: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Returns true when any of the documented skip-confirmation
+      # flags is present. `--yes` / `-y` is the canonical form;
+      # `--force` / `-f` is the Unix-conventional synonym accepted
+      # so users' muscle memory works. Either form skips the
+      # interactive `Proceed? [y/N]` prompt.
+      # @api private
+      SKIP_CONFIRMATION_FLAGS = %w[--yes -y --force -f].freeze
+
+      # @api private
+      def self.skip_confirmation?(args)
+        args.any? { |arg| SKIP_CONFIRMATION_FLAGS.include?(arg) }
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.existing_targets
+        [RSpecTracer.cache_path, RSpecTracer.coverage_path, RSpecTracer.report_path]
+          .select { |path| File.directory?(path) }
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.nothing_to_remove(stdout)
+        stdout.puts 'cache:clear: nothing to remove (cache directories do not exist)'
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.announce(stdout, existing)
+        stdout.puts 'cache:clear: will remove:'
+        existing.each { |path| stdout.puts "  - #{path}" }
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.confirm?(stdout)
+        stdout.print 'Proceed? [y/N] '
+        stdout.flush
+        response = $stdin.gets&.chomp&.downcase
+        %w[y yes].include?(response)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.aborted(stdout)
+        stdout.puts 'cache:clear: aborted'
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remove_each(stdout, existing)
+        existing.each do |path|
+          FileUtils.rm_rf(path)
+          stdout.puts "  removed #{path}"
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: rspec-tracer cache:clear [--yes | --force]
+
+          Remove cache, coverage, and report directories. The next rspec
+          run will be a cold run (full re-execution + cache rebuild).
+
+          Options:
+            -y, --yes     Skip the confirmation prompt.
+            -f, --force   Synonym for --yes.
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/rspec_tracer/cli/cache_info.rb

@@ -0,0 +1,104 @@
+# 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 cache:info` — show cache size, last run, and
+    # invalidation stats. Backend-agnostic: dispatches through
+    # {RSpecTracer::Storage::Backend.build} so `storage_backend
+    # :sqlite` reports the populated cache instead of the false
+    # "no cache yet" the JsonBackend-only path used to emit.
+    module CacheInfo
+      # @param args [Array<String>] sub-command args (`-h` / `--help`).
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = success).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+
+        cache_path = RSpecTracer.cache_path
+        stdout.puts "cache_path: #{cache_path}"
+        stdout.puts "size:       #{format_bytes(directory_size(cache_path))}"
+
+        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?
+          stdout.puts 'last_run:   no cache yet (run rspec first)'
+          return 0
+        end
+
+        stdout.puts "last_run:   #{run_id}"
+        print_example_count(stdout, backend)
+        0
+      rescue StandardError => e
+        stderr.puts "cache:info: #{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 cache:info
+
+          Show the on-disk cache size, the last run id, and example counts
+          for the most recent run. Backend-aware: works under
+          `storage_backend :json` (default) and `storage_backend :sqlite`.
+          Read-only; does not modify the cache.
+        HELP
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_example_count(stdout, backend)
+        snapshot = backend.load_graph(schema_version: Storage::Schema::CURRENT)
+        if snapshot.nil?
+          stdout.puts 'examples:   <unknown> (schema mismatch; next rspec run will be cold)'
+          return
+        end
+
+        stdout.puts "examples:   #{snapshot.all_examples.size} tracked"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.directory_size(path)
+        return 0 unless File.directory?(path)
+
+        total = 0
+        Dir.glob(File.join(path, '**', '*'), File::FNM_DOTMATCH).each do |entry|
+          next unless File.file?(entry)
+
+          total += File.size(entry)
+        rescue SystemCallError
+          next
+        end
+        total
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.format_bytes(bytes)
+        return '0 B' if bytes <= 0
+
+        units = %w[B KB MB GB]
+        scale = bytes
+        unit_index = 0
+        while scale >= 1024 && unit_index < units.length - 1
+          scale /= 1024.0
+          unit_index += 1
+        end
+        format('%<scale>.1f %<unit>s', scale: scale, unit: units[unit_index])
+      end
+    end
+  end
+end

data/lib/rspec_tracer/cli/doctor.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer doctor` — diagnose config + environment.
+    # Reports Ruby + rspec-tracer 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')
+
+        require 'rspec_tracer/load_config'
+
+        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
+        ]
+        checks.each { |line| stdout.puts line }
+        ok = checks.none? { |line| line.start_with?('FAIL') }
+        ok ? 0 : 1
+      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: rspec-tracer doctor
+
+          Diagnose rspec-tracer 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   rspec-tracer: #{RSpecTracer::VERSION}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.project_root_check
+        "OK   root:        #{RSpecTracer.root}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.cache_path_check
+        path_check('cache_path:', RSpecTracer.cache_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.coverage_path_check
+        path_check('coverage_path:', RSpecTracer.coverage_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.report_path_check
+        path_check('report_path:', RSpecTracer.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 rspec-tracer doctor` runs in its own process via
+      # the gem's `bin/rspec-tracer` 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 'rspec_tracer/storage/schema'
+        require 'json'
+
+        cache_path = RSpecTracer.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 = RSpecTracer::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 RSpecTracer.respond_to?(:remote_cache_backend_entry)
+
+        RSpecTracer.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('RSPEC_TRACER_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 rspec-tracer bucket and
+      # attribution silently widens. Same shape as the boot-time warn
+      # in RSpecTracer.start, surfaced here so users running
+      # `rspec-tracer 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
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.ar_schema_enabled?
+        return false unless RSpecTracer.respond_to?(:track_ar_schema_notifications?)
+
+        RSpecTracer.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