testsift 0.0.1

data/lib/testsift.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require 'English'
+
+require 'digest/md5'
+require 'docile'
+require 'fileutils'
+require 'forwardable'
+require 'json'
+require 'pathname'
+require 'set'
+
+require_relative 'testsift/defaults'
+require_relative 'testsift/engine'
+require_relative 'testsift/example'
+# Reporters must load before load_config so the Configuration DSL's
+# `add_reporter` can validate symbol names against
+# `Reporters::Registry::BUILT_INS` when a user `.testsift` calls
+# it at configure time.
+require_relative 'testsift/reporters/base'
+require_relative 'testsift/reporters/payload_builder'
+require_relative 'testsift/reporters/coverage_json_reporter'
+require_relative 'testsift/reporters/json_reporter'
+require_relative 'testsift/reporters/terminal_reporter'
+require_relative 'testsift/reporters/html_reporter'
+require_relative 'testsift/reporters/registry'
+require_relative 'testsift/load_config'
+# RemoteCache is loaded lazily from its Rakefile shim (user-driven),
+# not at gem-load time. The user-facing tasks `testsift:remote_cache:*`
+# pull in `lib/testsift/remote_cache.rb` when the user's Rakefile
+# loads the shim. Test-suite runs that never invoke a cache task pay
+# zero load cost for aws/git subshell code.
+require_relative 'testsift/rspec/installation'
+require_relative 'testsift/rspec/parallel_tests'
+require_relative 'testsift/rspec/rails_setup'
+require_relative 'testsift/source_file'
+require_relative 'testsift/time_formatter'
+require_relative 'testsift/version'
+
+# Top-level entry point. Drives the lifecycle:
+#
+#   TestSift.start
+#     -> RSpec::Installation.install!  (prepend RunnerHook + ReporterHook)
+#     -> setup_coverage                (::Coverage.start unless SimpleCov owns it)
+#     -> setup_rails                   (detect ::Rails::VERSION)
+#     -> Engine.new.setup              (observers + cache load + filter decisions)
+#
+#   at_exit_behavior (installed via `at_exit` elsewhere in the boot
+#   flow) runs the finalize stack: Engine#finalize writes the 13-file
+#   snapshot via Storage::JsonBackend, Reporters::CoverageJsonReporter
+#   writes coverage.json (single owner, replacing the 1.x
+#   CoverageReporter + CoverageWriter pair retired in 2.0),
+#   ParallelTests#finalize! merges per-worker caches on the last worker.
+module TestSift
+  class << self
+    # Internal attribute.
+    # @api private
+    attr_accessor :running, :pid, :no_examples, :duplicate_examples
+
+    # Boot the tracer. Idempotent — safe to call multiple times in a
+    # single process (subsequent calls return without re-installing
+    # hooks). Drives the lifecycle:
+    #
+    #   * Installs the RSpec runner / reporter prepend chain.
+    #   * Starts `::Coverage` unless SimpleCov already owns it.
+    #   * Detects Rails (memoized in `TestSift.rails?`).
+    #   * Builds the {TestSift::Engine} and installs observers.
+    #
+    # Must be called BEFORE any application code loads so the boot
+    # set captured by `Coverage.peek_result` is empty. With SimpleCov,
+    # call `SimpleCov.start` first; testsift warns at boot when
+    # SimpleCov is loaded but not started.
+    #
+    # @return [void]
+    def start
+      return if defined?(@started) && @started
+
+      TestSift.running = false
+      TestSift.pid = Process.pid
+      @run_started_at = ::Time.now.utc
+      @run_monotonic_start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      @started = true
+
+      TestSift.logger.debug "Started TestSift (pid: #{TestSift.pid})"
+
+      warn_on_simplecov_load_order_mistake
+
+      @parallel_tests = TestSift::RSpec::ParallelTests.active?
+      TestSift::RSpec::ParallelTests.setup! if parallel_tests?
+      initial_setup
+    end
+
+    # SimpleCov load-order is part of the documented contract -
+    # SimpleCov.start MUST run before TestSift.start when both are
+    # used together (see README §SimpleCov interop). When the user
+    # has SimpleCov loaded but not started, we'd silently call
+    # ::Coverage.start ourselves and SimpleCov's later setup would
+    # bolt onto a Coverage already in flight, with the user's
+    # add_filter calls applied after testsift started consuming
+    # data. Surface the load-order mistake at start time so the user
+    # gets a one-line warning instead of mysteriously-broken
+    # coverage output.
+    def warn_on_simplecov_load_order_mistake
+      return unless defined?(::SimpleCov)
+      return if ::SimpleCov.respond_to?(:running) && ::SimpleCov.running
+
+      TestSift.logger.warn(
+        'SimpleCov is loaded but not started. ' \
+        'Call SimpleCov.start before TestSift.start so the ' \
+        'tracer respects SimpleCov\'s filter chain. See README ' \
+        'section "Working with SimpleCov".'
+      )
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def at_exit_behavior
+      return unless TestSift.pid == Process.pid && TestSift.running
+
+      ::Kernel.exit(1) if duplicate_examples
+
+      run_exit_tasks
+    ensure
+      if TestSift::RSpec::ParallelTests.active? &&
+          TestSift::RSpec::ParallelTests.last_process?
+        TestSift::RSpec::ParallelTests.remove_lock_file!
+      end
+
+      TestSift.running = false
+    end
+
+    # The current {TestSift::Engine} instance, or nil if
+    # {.start} hasn't been called yet.
+    #
+    # @return [TestSift::Engine, nil]
+    def engine
+      @engine if defined?(@engine)
+    end
+
+    # True if SimpleCov was loaded AND running at the time
+    # {.start} was invoked. Determines whether testsift
+    # owns `::Coverage.start` itself (false) or defers to
+    # SimpleCov's coverage lifecycle (true).
+    #
+    # @return [Boolean]
+    def simplecov?
+      defined?(@simplecov) && @simplecov == true
+    end
+
+    # True if `parallel_tests` is in use (detected via
+    # `ParallelTests.active?` at {.start} time). Affects
+    # cache + report directory scoping (per-worker dirs)
+    # and finalize-time merging.
+    #
+    # @return [Boolean]
+    def parallel_tests?
+      defined?(@parallel_tests) && @parallel_tests == true
+    end
+
+    # True if Rails is loaded in this process (detected via
+    # `defined?(::Rails::VERSION)` at {.start} time). Memoized;
+    # subsequent Rails activations within the same run are not
+    # re-detected. Drives the auto-installation of Rails-side
+    # observers (template + AR notification subscribers).
+    #
+    # @return [Boolean]
+    def rails?
+      defined?(@rails) && @rails == true
+    end
+
+    private
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def initial_setup
+      TestSift::RSpec::Installation.install!
+
+      setup_coverage
+      setup_rails
+
+      @engine = TestSift::Engine.new(
+        configuration: TestSift,
+        read_cache_path: parallel_tests? ? File.dirname(TestSift.cache_path) : nil
+      )
+      @engine.setup
+      TestSift::RSpec::RailsSetup.install(engine: @engine, configuration: TestSift)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def setup_coverage
+      @simplecov = defined?(SimpleCov) && SimpleCov.running
+
+      return if simplecov?
+
+      require 'coverage'
+
+      return if ::Coverage.respond_to?(:running?) && ::Coverage.running?
+
+      ::Coverage.start(**coverage_modes_for_start)
+    rescue RuntimeError
+      # ::Coverage.start raises if already started on some Rubies
+      # without a running? predicate; safe to ignore (matches
+      # Engine#ensure_coverage_started behavior).
+      nil
+    end
+
+    # Detects Rails by the presence of `::Rails::VERSION`. Users who
+    # require `testsift/rails` transitively load the Railtie (when
+    # Rails is also present); this method only sets the flag consumed
+    # by `TestSift.rails?`. Safe when Rails is absent - the
+    # `defined?` guard returns nil, flag stays false.
+    def setup_rails
+      @rails = defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def run_exit_tasks
+      if TestSift.no_examples
+        TestSift.logger.info 'Skipped reports generation since all examples were filtered out'
+      else
+        snapshot = run_finalize
+        # Under parallel_tests, defer reporter emission until
+        # last-process finalize merges per-worker snapshots into the
+        # top-level cache. Each worker still persists its per-worker
+        # snapshot for the merge to consume. Earlier behavior had every
+        # worker emit reporters into testsift_report/parallel_tests_N/
+        # and purge_worker_dirs! removed those dirs - leaving the user
+        # with no usable terminal/JSON/HTML output. Now reporters fire
+        # ONCE at the merged top-level location.
+        emit_reporters(snapshot) if snapshot && !parallel_tests?
+      end
+
+      emit_coverage_json
+
+      TestSift::RSpec::ParallelTests.finalize! if parallel_tests?
+    end
+
+    # Engine-owned finalize path. Writes the 15-file JSON cache via
+    # Storage::JsonBackend. Per-example coverage deltas live on the
+    # Engine; 2.0 retired the CoverageReporter mid-flow piece (the
+    # legacy `coverage_reporter.generate_final_examples_coverage +
+    # merge_coverage(engine.merge_skipped_coverage(...))` is now folded
+    # into Reporters::CoverageJsonReporter#generate, which fires from
+    # `emit_coverage_json` after this method returns).
+    def run_finalize
+      starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      snapshot = engine.finalize
+
+      ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      elapsed = TestSift::TimeFormatter.format_time(ending - starting)
+
+      TestSift.logger.debug "TestSift persisted cache (took #{elapsed})"
+      snapshot
+    rescue StandardError => e
+      # Graceful-degradation contract per ARCHITECTURE.md
+      # section Cache corruption recovery: never propagate storage errors
+      # into the user's test suite. Read-only cache_path, disk-full
+      # mid-write, permission flips between runs - log and skip
+      # report emission. The caller (run_exit_tasks) checks for nil
+      # before calling emit_reporters; coverage / parallel_tests
+      # finalize paths run independently downstream.
+      TestSift.logger.warn(
+        "testsift: cache persistence failed (#{e.class}: #{e.message}); " \
+        'skipping report generation. Verify cache_path is writable.'
+      )
+      nil
+    end
+
+    # Fire the configured reporters against the persisted
+    # Snapshot. Fires per-worker under parallel_tests (same cadence as
+    # coverage.json emission); each worker produces its own report.json
+    # under its per-worker report_dir. The Registry rescues every
+    # reporter individually, so a buggy reporter warns and continues -
+    # never propagates a non-zero exit into the user's test suite
+    # (graceful degradation contract, same as Storage backends).
+    def emit_reporters(snapshot)
+      TestSift::Reporters::Registry.emit_all(
+        configuration: TestSift,
+        snapshot: snapshot,
+        report_dir: TestSift.report_path,
+        run_metadata: build_run_metadata
+      )
+    rescue StandardError => e
+      TestSift.logger.warn(
+        "testsift: reporter pipeline failed (#{e.class}: #{e.message})"
+      )
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def build_run_metadata
+      {
+        pid: TestSift.pid,
+        run_time: run_elapsed_seconds,
+        started_at: defined?(@run_started_at) ? @run_started_at : nil,
+        cache_path: TestSift.cache_path,
+        parallel_tests: TestSift.parallel_tests?,
+        rails: TestSift.rails?
+      }
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def run_elapsed_seconds
+      return nil unless defined?(@run_monotonic_start) && @run_monotonic_start
+
+      (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - @run_monotonic_start).round(4)
+    end
+
+    # Dedicated coverage.json firing path, parallel to the
+    # report-reporters Registry pipeline. Fires unconditionally - even
+    # when no examples ran (matches 1.x where coverage.json gets
+    # written with whatever boot-time peek_result returned + filter +
+    # stub). The emitter handles SimpleCov interop internally
+    # (installs `::Coverage.singleton_class.prepend` shim instead of
+    # writing coverage.json when SimpleCov is loaded).
+    def emit_coverage_json
+      return unless engine
+
+      TestSift::Reporters::CoverageJsonReporter.new(
+        snapshot: nil,
+        report_dir: TestSift.report_path,
+        run_metadata: build_run_metadata,
+        logger: TestSift.logger
+      ).generate
+    rescue StandardError => e
+      TestSift.logger.warn(
+        "testsift: coverage.json emit failed (#{e.class}: #{e.message})"
+      )
+    end
+  end
+end

metadata

@@ -0,0 +1,193 @@
+--- !ruby/object:Gem::Specification
+name: testsift
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Sebastian Sala
+- Abhimanyu Singh
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: docile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: TestSift records the inputs each RSpec example consumes -- using Ruby's
+  built-in coverage library plus explicit declarations -- and turns that record into
+  a flaky-test detector, a per-example dependency map, and optional CI acceleration
+  that skips the examples whose recorded inputs are unchanged. It never skips failed,
+  flaky, or pending examples.
+email:
+executables:
+- testsift
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/testsift
+- lib/testsift.rb
+- lib/testsift/cache/Rakefile
+- lib/testsift/cli.rb
+- lib/testsift/cli/blast_radius.rb
+- lib/testsift/cli/cache_clear.rb
+- lib/testsift/cli/cache_info.rb
+- lib/testsift/cli/doctor.rb
+- lib/testsift/cli/explain.rb
+- lib/testsift/cli/report_open.rb
+- lib/testsift/cli/snapshot_helpers.rb
+- lib/testsift/configuration.rb
+- lib/testsift/defaults.rb
+- lib/testsift/engine.rb
+- lib/testsift/engine/snapshot_builder.rb
+- lib/testsift/example.rb
+- lib/testsift/filter.rb
+- lib/testsift/line_stub.rb
+- lib/testsift/load_config.rb
+- lib/testsift/load_default_config.rb
+- lib/testsift/load_global_config.rb
+- lib/testsift/load_local_config.rb
+- lib/testsift/logger.rb
+- lib/testsift/rails.rb
+- lib/testsift/rails/README.md
+- lib/testsift/rails/i18n_tracking.rb
+- lib/testsift/rails/notifications.rb
+- lib/testsift/rails/preset.rb
+- lib/testsift/rails/railtie.rb
+- lib/testsift/remote_cache.rb
+- lib/testsift/remote_cache/README.md
+- lib/testsift/remote_cache/Rakefile
+- lib/testsift/remote_cache/archive.rb
+- lib/testsift/remote_cache/backend.rb
+- lib/testsift/remote_cache/git_ancestry.rb
+- lib/testsift/remote_cache/local_fs_backend.rb
+- lib/testsift/remote_cache/redis_backend.rb
+- lib/testsift/remote_cache/s3_backend.rb
+- lib/testsift/remote_cache/user_tasks.rb
+- lib/testsift/remote_cache/validator.rb
+- lib/testsift/reporters/README.md
+- lib/testsift/reporters/base.rb
+- lib/testsift/reporters/coverage_json_reporter.rb
+- lib/testsift/reporters/html/.gitignore
+- lib/testsift/reporters/html/.prettierignore
+- lib/testsift/reporters/html/.prettierrc.json
+- lib/testsift/reporters/html/README.md
+- lib/testsift/reporters/html/dist/assets/index.css
+- lib/testsift/reporters/html/dist/assets/index.js
+- lib/testsift/reporters/html/dist/index.html
+- lib/testsift/reporters/html/eslint.config.js
+- lib/testsift/reporters/html/package-lock.json
+- lib/testsift/reporters/html/package.json
+- lib/testsift/reporters/html/src/app.jsx
+- lib/testsift/reporters/html/src/components/AllExamples.jsx
+- lib/testsift/reporters/html/src/components/DuplicateExamples.jsx
+- lib/testsift/reporters/html/src/components/ExamplesDependency.jsx
+- lib/testsift/reporters/html/src/components/FilesDependency.jsx
+- lib/testsift/reporters/html/src/components/FlakyExamples.jsx
+- lib/testsift/reporters/html/src/components/ReportTable.jsx
+- lib/testsift/reporters/html/src/components/SearchBar.jsx
+- lib/testsift/reporters/html/src/index.html
+- lib/testsift/reporters/html/src/main.jsx
+- lib/testsift/reporters/html/src/styles.css
+- lib/testsift/reporters/html/vite.config.js
+- lib/testsift/reporters/html_reporter.rb
+- lib/testsift/reporters/json_reporter.rb
+- lib/testsift/reporters/payload_builder.rb
+- lib/testsift/reporters/registry.rb
+- lib/testsift/reporters/terminal_reporter.rb
+- lib/testsift/rspec/README.md
+- lib/testsift/rspec/installation.rb
+- lib/testsift/rspec/metadata.rb
+- lib/testsift/rspec/parallel_tests.rb
+- lib/testsift/rspec/rails_setup.rb
+- lib/testsift/rspec/reporter_hook.rb
+- lib/testsift/rspec/runner_hook.rb
+- lib/testsift/source_file.rb
+- lib/testsift/storage/README.md
+- lib/testsift/storage/backend.rb
+- lib/testsift/storage/json_backend.rb
+- lib/testsift/storage/lazy_snapshot.rb
+- lib/testsift/storage/schema.rb
+- lib/testsift/storage/serializer/json.rb
+- lib/testsift/storage/serializer/msgpack.rb
+- lib/testsift/storage/snapshot.rb
+- lib/testsift/storage/sqlite_backend.rb
+- lib/testsift/time_formatter.rb
+- lib/testsift/tracker/README.md
+- lib/testsift/tracker/coverage_adapter.rb
+- lib/testsift/tracker/declared_globs.rb
+- lib/testsift/tracker/dependency_graph.rb
+- lib/testsift/tracker/env_matcher.rb
+- lib/testsift/tracker/env_snapshot.rb
+- lib/testsift/tracker/example_registry.rb
+- lib/testsift/tracker/file_digest.rb
+- lib/testsift/tracker/filter.rb
+- lib/testsift/tracker/input.rb
+- lib/testsift/tracker/io_hooks.rb
+- lib/testsift/tracker/io_hooks/file.rb
+- lib/testsift/tracker/io_hooks/io.rb
+- lib/testsift/tracker/io_hooks/json.rb
+- lib/testsift/tracker/io_hooks/kernel.rb
+- lib/testsift/tracker/io_hooks/yaml.rb
+- lib/testsift/tracker/loaded_files_tracker.rb
+- lib/testsift/tracker/new_file_detector.rb
+- lib/testsift/tracker/whole_suite_invalidators.rb
+- lib/testsift/version.rb
+homepage: https://github.com/salasebas/testsift
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/salasebas/testsift
+  source_code_uri: https://github.com/salasebas/testsift/tree/v0.0.1
+  changelog_uri: https://github.com/salasebas/testsift/blob/v0.0.1/CHANGELOG.md
+  bug_tracker_uri: https://github.com/salasebas/testsift/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'Affected-test selection for RSpec: re-run only the examples whose recorded
+  inputs changed, with flaky-test detection and a per-example dependency map.'
+test_files: []