testsift 0.0.1

data/lib/testsift/cli/snapshot_helpers.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'testsift/storage/backend'
+require 'testsift/storage/json_backend'
+require 'testsift/storage/schema'
+require 'testsift/storage/sqlite_backend' if RUBY_ENGINE == 'ruby'
+
+module TestSift
+  # Internal CLI -- see {TestSift} for the user-facing surface.
+  # @api private
+  module CLI
+    # Shared plumbing for the snapshot-reading sub-commands (Explain,
+    # BlastRadius): help-flag detection, backend-agnostic snapshot
+    # loading with uniform degradation messages, and String/Symbol-
+    # tolerant metadata lookups. Extracted so the two commands cannot
+    # drift apart on message wording or cache-shape tolerance.
+    # @api private
+    module SnapshotHelpers
+      # @param args [Array<String>] sub-command args (flags removed
+      #   by the caller where applicable)
+      # @return [Boolean] true when the sub-command should print its
+      #   help text instead of executing
+      def self.help_requested?(args)
+        args.empty? || args.include?('-h') || args.include?('--help')
+      end
+
+      # Resolve the persisted snapshot through the configured storage
+      # backend ({TestSift::Storage::Backend.build}), so
+      # `storage_backend :sqlite` resolves the latest run from the
+      # meta table instead of the JsonBackend-only `last_run.json`.
+      #
+      # @param cache_path [String] root cache directory
+      # @param command [String] sub-command name used as the message
+      #   prefix (e.g. `explain`, `blast-radius`)
+      # @param stderr [IO]
+      # @return [Array(Object, Object), nil] `[snapshot, backend]` on
+      #   success; nil (after printing a one-line explanation) when no
+      #   run has been recorded yet or the cache schema is
+      #   incompatible
+      def self.load_snapshot(cache_path, command:, stderr:)
+        backend = Storage::Backend.build(cache_path: cache_path, configuration: TestSift)
+        run_id = backend.last_run_id
+        if run_id.nil? || run_id.to_s.empty?
+          stderr.puts "#{command}: 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 "#{command}: cache at #{cache_path} is incompatible with this testsift; " \
+                      'next rspec run is cold'
+          return nil
+        end
+
+        [snapshot, backend]
+      end
+
+      # Whether the backend persists the per-run filter decisions
+      # (`filtered_examples` / `skipped_examples`). JsonBackend does;
+      # SqliteBackend deliberately does not (its `dispatch_read`
+      # returns `{}` for those fields). Callers use this to attribute
+      # an empty decision set honestly: on a persisting backend it
+      # means "no decision was recorded for this id" (cold run, or the
+      # id was not part of the last run), NOT a backend limitation.
+      #
+      # @param backend [Object] a {TestSift::Storage::Backend.build}
+      #   product
+      # @return [Boolean]
+      def self.filter_decisions_persisted?(backend)
+        backend.is_a?(Storage::JsonBackend)
+      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
+
+      # The example's rerun location from persisted all_examples meta,
+      # preferring the rerun_* fields the reporter records.
+      #
+      # @param meta [Hash] one all_examples entry
+      # @return [Array(Object, Object)] `[file, line]`; either element
+      #   may be nil when the meta is missing the field
+      def self.example_location(meta)
+        [
+          fetch_meta(meta, 'rerun_file_name', 'file_name'),
+          fetch_meta(meta, 'rerun_line_number', 'line_number')
+        ]
+      end
+
+      # @param meta [Hash] one all_examples entry
+      # @return [String, nil] the example's description, or nil when
+      #   the meta is missing both description fields
+      def self.example_description(meta)
+        fetch_meta(meta, 'full_description', 'description')
+      end
+    end
+  end
+end

data/lib/testsift/cli.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+# Only the Logger class -- NOT the full library, whose boot would
+# `load` the project config. {CLI.with_default_logger_out} needs the
+# class defined before that boot so the config-load window cannot
+# construct a stdout-bound logger.
+require_relative 'logger'
+
+module TestSift
+  # Command-line entry for the `testsift` binary. Six sub-commands
+  # per USER_FACING_SURFACE.md section 10: `doctor`, `cache:info`,
+  # `cache:clear`, `report:open`, `explain <example>`,
+  # `blast-radius <file>`.
+  #
+  # The CLI is opt-in — the canonical CI flow continues to go through
+  # `rake testsift:remote_cache:*` tasks per USER_FACING_SURFACE.md
+  # §5. Sub-commands operate against the local cache + report
+  # directories resolved from the project's `.testsift` config.
+  # {.run} loads the tracer library (and with it the project + global
+  # `.testsift` configs) via {.load_tracer} right before
+  # sub-command dispatch, so `--help` / `--version` work even in a
+  # project whose config is broken, and a config file that raises at
+  # load time degrades to a one-line message + exit 1 instead of a
+  # raw backtrace.
+  #
+  # @api private
+  module CLI
+    # Internal constant.
+    # @api private
+    SUB_COMMANDS = {
+      'doctor' => 'Doctor',
+      'cache:info' => 'CacheInfo',
+      'cache:clear' => 'CacheClear',
+      'report:open' => 'ReportOpen',
+      'explain' => 'Explain',
+      'blast-radius' => 'BlastRadius'
+    }.freeze
+
+    # CLI entry. Called by `bin/testsift` 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)
+
+      with_default_logger_out(stderr) do
+        if load_tracer(stderr)
+          with_logger_on(stderr) { dispatch(args, stdout: stdout, stderr: stderr) }
+        else
+          1
+        end
+      end
+    rescue Errno::EPIPE
+      # A downstream pipe consumer (`testsift ... | head`) closed
+      # early -- routine in shell pipelines, not a failure. Exit 0
+      # without printing: writing to stderr could raise EPIPE again
+      # when both streams share the closed pipe.
+      0
+    rescue StandardError => e
+      stderr.puts "testsift: #{e.class}: #{e.message}"
+      1
+    end
+
+    # Boot the tracer library for sub-command dispatch. Loading
+    # `testsift` pulls in `docile` (used by
+    # `Configuration#configure`), the modules sub-commands rely on,
+    # AND the project's `.testsift` / `~/.testsift` configs
+    # (arbitrary user Ruby, `load`ed by `load_config`). It does NOT
+    # call `TestSift.start` - the engine stays inert until a user
+    # invokes it explicitly.
+    #
+    # A raising config must not crash the binary with a backtrace:
+    # rescue ScriptError as well as StandardError because a syntax
+    # error in `.testsift` raises SyntaxError, which is not a
+    # StandardError and would sail past {.run}'s rescue.
+    #
+    # @param stderr [IO]
+    # @return [Boolean] true when the tracer library (and the user
+    #   configs it loads) booted cleanly
+    def self.load_tracer(stderr)
+      require 'testsift'
+      true
+    rescue ScriptError, StandardError => e
+      stderr.puts "testsift: could not load configuration (.testsift): #{e.class}: #{e.message}"
+      false
+    end
+
+    # Point {TestSift::Logger.default_out} at the CLI's stderr for
+    # the duration of library boot + sub-command dispatch, restoring
+    # the previous value afterwards. This must wrap {.load_tracer}:
+    # booting the library `load`s the project + global `.testsift`
+    # configs, and those can write through the logger BEFORE
+    # {.with_logger_on} ever runs -- the 1.x-compat deprecation shims
+    # (`reports_s3_path`, `use_local_aws`) fire a one-time
+    # `logger.warn` at first use, and in a fresh CLI process
+    # "one-time" means every invocation. The logger's default
+    # destination is stdout -- the stream machine consumers parse --
+    # so that warning would land ahead of e.g. the `blast-radius
+    # --json` document and break `| jq`. With the default rebound,
+    # every logger constructed during the window binds to stderr,
+    # including loggers recreated mid-load when a config sets
+    # `log_level` (which resets the memoized instance) after a
+    # deprecated DSL call. Normal `rspec` runs (whose users expect
+    # stdout logs) never enter this path and stay untouched.
+    # @api private
+    def self.with_default_logger_out(stderr)
+      previous = TestSift::Logger.default_out
+      TestSift::Logger.default_out = stderr
+      yield
+    ensure
+      TestSift::Logger.default_out = previous
+    end
+
+    # Bind the tracer's internal logger to the CLI's stderr for the
+    # duration of sub-command dispatch, restoring the previous logger
+    # afterwards. Backend diagnostics run through `TestSift.logger`
+    # (e.g. {TestSift::Storage::Backend.build}'s sqlite-unavailable
+    # fallback warning, JsonBackend's schema-mismatch info line).
+    # {.with_default_logger_out} already redirects loggers constructed
+    # during the CLI window; this layer additionally rebinds a logger
+    # that was memoized into `TestSift.@logger` BEFORE {.run} was
+    # called (possible for in-process callers -- the spec suite, or a
+    # user embedding the CLI -- where the library booted earlier with
+    # the stdout default). Sub-commands like `blast-radius --json`
+    # promise exactly one JSON document on stdout, so a diagnostic
+    # line printed ahead of it breaks `| jq`; together the two layers
+    # keep ALL diagnostics on stderr alongside the CLI's own messages.
+    #
+    # `TestSift.logger` memoizes into `@logger`
+    # (Configuration#logger); the ivar is seeded directly because
+    # Configuration deliberately exposes no logger setter -- adding
+    # one would leak it into the user-facing `configure` DSL surface.
+    # @api private
+    def self.with_logger_on(stderr)
+      previous = TestSift.instance_variable_get(:@logger)
+      TestSift.instance_variable_set(
+        :@logger, TestSift::Logger.new(TestSift.log_level, out: stderr)
+      )
+      yield
+    ensure
+      TestSift.instance_variable_set(:@logger, previous)
+    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)
+      TestSift::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 "testsift: 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: testsift <sub-command> [options]
+
+        Sub-commands:
+          doctor          Diagnose testsift 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.
+          blast-radius <f>  Show which examples a file change would re-run.
+
+        Options:
+          -h, --help      Print this help message.
+          -v, --version   Print testsift version.
+
+        Run `testsift <sub-command> --help` for sub-command options.
+      HELP
+      0
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.print_version(stdout)
+      # Only the version constant - not the full library, whose boot
+      # would `load` the project config and could raise before the
+      # version ever printed.
+      require 'testsift/version'
+      stdout.puts "testsift #{TestSift::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
+      # `testsift: <class>: <message>` and exits 1.
+      raise StandardError, "could not load sub-command #{klass_name.inspect}: #{e.message}"
+    end
+  end
+end