testsift 0.0.1

data/lib/testsift/engine.rb

@@ -0,0 +1,896 @@
+# frozen_string_literal: true
+
+require 'coverage'
+require 'digest'
+require 'json'
+require 'set'
+
+require_relative 'engine/snapshot_builder'
+require_relative 'tracker/coverage_adapter'
+require_relative 'tracker/declared_globs'
+require_relative 'tracker/dependency_graph'
+require_relative 'tracker/env_matcher'
+require_relative 'tracker/env_snapshot'
+require_relative 'tracker/example_registry'
+require_relative 'tracker/file_digest'
+require_relative 'tracker/filter'
+require_relative 'tracker/input'
+require_relative 'tracker/io_hooks'
+require_relative 'tracker/loaded_files_tracker'
+require_relative 'tracker/new_file_detector'
+require_relative 'tracker/whole_suite_invalidators'
+require_relative 'storage/backend'
+require_relative 'storage/json_backend'
+require_relative 'storage/schema'
+require_relative 'storage/snapshot'
+require_relative 'storage/sqlite_backend'
+
+module TestSift
+  # rubocop:disable Metrics/ClassLength
+  class Engine
+    include SnapshotBuilder
+
+    # Internal constant.
+    # @api private
+    EXAMPLE_RUN_REASON = {
+      explicit_run: 'Explicit run',
+      no_cache: 'No cache',
+      interrupted: 'Interrupted previously',
+      flaky_example: 'Flaky example',
+      failed_example: 'Failed previously',
+      pending_example: 'Pending previously',
+      files_changed: 'Files changed',
+      whole_suite_invalidator: 'Whole-suite invalidator changed',
+      env_changed: 'Environment changed'
+    }.freeze
+
+    # Map from Filter#select reasons to the legacy-shaped strings
+    # users see in test output ("foo (Files changed)"). Keeps the
+    # user surface unchanged under v2.
+    FILTER_REASON_STRINGS = {
+      whole_suite_invalidator: EXAMPLE_RUN_REASON[:whole_suite_invalidator],
+      interrupted: EXAMPLE_RUN_REASON[:interrupted],
+      flaky_example: EXAMPLE_RUN_REASON[:flaky_example],
+      failed_example: EXAMPLE_RUN_REASON[:failed_example],
+      pending_example: EXAMPLE_RUN_REASON[:pending_example],
+      no_cache: EXAMPLE_RUN_REASON[:no_cache],
+      files_changed: EXAMPLE_RUN_REASON[:files_changed],
+      env_changed: EXAMPLE_RUN_REASON[:env_changed]
+    }.freeze
+
+    # Internal attribute.
+    # @api private
+    attr_reader :registry, :graph, :loaded_files_tracker, :coverage_adapter,
+                :declared_globs, :whole_suite_invalidators, :new_file_detector,
+                :env_snapshot, :storage_backend, :all_examples, :duplicate_examples,
+                :examples_coverage, :all_files
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def initialize(configuration:, read_cache_path: nil)
+      @configuration = configuration
+      @read_cache_path = read_cache_path
+      @filtered_examples = {}
+      @all_examples = {}
+      @duplicate_examples = {}
+      @examples_coverage = {}
+      @all_files = {}
+      @file_names = {}
+      @absolute_paths = {}
+      @filter_decisions = {}
+      @tracks_files = Hash.new { |h, id| h[id] = Set.new } # id => Set<abs_path>
+      @tracks_env = Hash.new { |h, id| h[id] = Set.new }   # id => Set<env_name>
+      @tracked_env_names = Set.new
+      @config_tracked_env_names = Set.new # config-level subset (post-expansion)
+      @previous_snapshot = nil
+      @run_id = nil
+      @before_peek = nil
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def setup
+      @configuration.freeze_declared_globs!
+
+      build_observers
+      install_io_hooks
+      install_rails_observers if @configuration.rails?
+      ensure_coverage_started
+
+      @loaded_files_tracker.capture_boot_set!
+      @declared_globs.walk
+
+      @previous_snapshot = load_previous_snapshot
+      seed_state_from_previous(@previous_snapshot) if @previous_snapshot
+      register_config_tracked_env_names
+      compute_filter_decisions
+      self
+    end
+
+    # --- filter-phase surface (mirrors legacy Runner) --------------
+
+    def run_example?(example_id)
+      return true if @configuration.run_all_examples
+
+      previously_seen = @previous_snapshot&.all_examples&.key?(example_id)
+      !previously_seen || @filtered_examples.key?(example_id)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def run_example_reason(example_id)
+      return EXAMPLE_RUN_REASON[:explicit_run] if @configuration.run_all_examples
+
+      @filtered_examples[example_id] || EXAMPLE_RUN_REASON[:no_cache]
+    end
+
+    def register_example(example)
+      example_id = example[:example_id]
+      @registry.register(example_id, metadata: example, identity_hash: example_id)
+      example.replace(@all_examples.fetch(example_id, {}).merge(example))
+      @all_examples[example_id] = example
+      @duplicate_examples[example_id] ||= []
+      @duplicate_examples[example_id] << example
+      self
+    end
+
+    # Per-example tracking DSL hook. Called from RunnerHook with the
+    # normalized `{files: Set<String>, env: Set<String>}` that
+    # `RSpec::Metadata.tracks_for(example)` produced. Resolves the
+    # file globs against the project root once per distinct glob
+    # string (memoized) and unions the matching Inputs into this
+    # example's dependency set. Env names are accumulated into
+    # `@tracked_env_names` so the finalize snapshot covers every key
+    # the run cared about.
+    #
+    # Per-example env entries may carry wildcard patterns (`tracks:
+    # { env: 'RAILS_*' }`). `EnvMatcher.expand` is the single funnel
+    # - literals pass through, wildcards expand against the live ENV,
+    # and unsupported syntax raises ArgumentError at this point
+    # (RunnerHook Pass 1, before any example body runs).
+    # rubocop:disable Metrics/PerceivedComplexity
+    def register_tracks(example_id, tracks)
+      files = tracks[:files] || tracks['files'] || Set.new
+      envs = tracks[:env] || tracks['env'] || Set.new
+
+      files.each { |glob| @tracks_files[example_id].merge(resolved_glob_inputs(glob)) } unless files.empty?
+      return self if envs.empty?
+
+      expanded = TestSift::Tracker::EnvMatcher.expand(envs.map(&:to_s))
+      @tracks_env[example_id].merge(expanded)
+      @tracked_env_names.merge(expanded)
+      self
+    end
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    # Called from RunnerHook AFTER the filter-decision pre-walk has
+    # populated `@tracks_env` / `@tracked_env_names` for every
+    # example. Compares each declared env key against the previous
+    # snapshot's `env_snapshot` via Tracker::EnvSnapshot; marks any
+    # example whose tracked-env set intersects the invalidated set
+    # as re-runnable. Strictly additive vs other filter reasons - if
+    # the example was already in `@filtered_examples` for a stronger
+    # reason (files_changed / whole_suite_invalidator /
+    # failed_example / ...), env_changed does NOT overwrite.
+    #
+    # Config-level path: when an invalidated key intersects
+    # `@config_tracked_env_names` (the post-expansion config-level
+    # set), every previously-seen example re-runs - mirrors the
+    # `track_files` "declared globs attach to every example"
+    # semantics. New examples (not in @previous_snapshot.all_examples)
+    # already run via the no_cache path; no special-casing needed.
+    def apply_env_filter_decisions
+      return self if @previous_snapshot.nil?
+      return self if @tracked_env_names.empty?
+
+      invalidated = @env_snapshot.invalidated_keys(
+        @previous_snapshot.env_snapshot, @tracked_env_names
+      )
+      return self if invalidated.empty?
+
+      reason = FILTER_REASON_STRINGS.fetch(:env_changed)
+      mark_all_prev_examples(reason) if invalidated.intersect?(@config_tracked_env_names)
+      mark_per_example_intersections(invalidated, reason)
+      self
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def deregister_duplicate_examples
+      @duplicate_examples.select! { |_, entries| entries.count > 1 }
+      return if @duplicate_examples.empty?
+
+      @all_examples.reject! { |id, _| @duplicate_examples.key?(id) }
+      self
+    end
+
+    # --- per-example surface --------------------------------------
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def example_started
+      @before_peek = @coverage_adapter.peek
+      @current_bucket = {}
+      @current_rails_bucket = {}
+      TestSift::Tracker::IOHooks.set_bucket(@current_bucket)
+      set_rails_bucket(@current_rails_bucket)
+      self
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def example_finished(example_id)
+      after_peek, coverage_paths = @coverage_adapter.peek_with_paths
+      record_coverage_delta(example_id, @before_peek, after_peek)
+      io_inputs = @current_bucket.values
+      rails_inputs = @current_rails_bucket ? @current_rails_bucket.values : []
+      TestSift::Tracker::IOHooks.clear_bucket
+      clear_rails_bucket
+
+      transitive_inputs = @loaded_files_tracker.loaded_set_inputs |
+        @loaded_files_tracker.stop_example(example_id, coverage_paths)
+      coverage_inputs = @coverage_adapter.compute_diff(@before_peek, after_peek)
+      declared_inputs = @declared_globs.walk
+      tracks_inputs = per_example_tracks_inputs(example_id)
+      attribute_to_example(
+        example_id,
+        coverage_inputs | transitive_inputs | io_inputs.to_set |
+          rails_inputs.to_set | declared_inputs | tracks_inputs
+      )
+
+      @before_peek = nil
+      @current_bucket = nil
+      @current_rails_bucket = nil
+      self
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def on_example_skipped(example_id)
+      @registry.register(example_id) unless @registry.registered?(example_id)
+      @registry.update_status(example_id, :skipped)
+      self
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def on_example_passed(example_id, result)
+      return if @duplicate_examples[example_id]&.count.to_i > 1
+
+      status = flaky_history?(example_id) ? :flaky : :passed
+      @registry.update_status(example_id, status)
+      record_execution_result(example_id, result)
+      self
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def on_example_failed(example_id, result)
+      return if @duplicate_examples[example_id]&.count.to_i > 1
+
+      status = previously_flaky?(example_id) ? :flaky : :failed
+      @registry.update_status(example_id, status)
+      record_execution_result(example_id, result)
+      self
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def on_example_pending(example_id, result)
+      return if @duplicate_examples[example_id]&.count.to_i > 1
+
+      @registry.update_status(example_id, :pending)
+      record_execution_result(example_id, result)
+      self
+    end
+
+    # --- finalize ------------------------------------------------
+
+    def finalize
+      @registry.all_example_ids.each do |id|
+        next if @registry.status_of(id)
+
+        @registry.update_status(id, :interrupted)
+      end
+
+      snapshot = build_snapshot
+      @storage_backend.save_graph(snapshot, schema_version: TestSift::Storage::Schema::CURRENT)
+      uninstall_rails_observers
+      snapshot
+    end
+
+    # For every previously-skipped example id, accumulate per-line
+    # coverage strengths from the previous run's per-example coverage
+    # map into the missed_coverage return value. Deleted files /
+    # missing entries are skipped silently. Consumed by
+    # Reporters::CoverageJsonReporter at finalize time so coverage.json
+    # carries forward the contribution of skipped examples.
+    #
+    # Returns Hash[file_path => Hash[line_number => cumulative_strength]].
+    def merge_skipped_coverage(skipped_ids, previous_examples_coverage = nil)
+      source = previous_examples_coverage || @previous_snapshot&.examples_coverage || {}
+      missed = Hash.new { |h, f| h[f] = Hash.new(0) }
+
+      skipped_ids.each do |example_id|
+        example_coverage = source[example_id]
+        next if example_coverage.nil?
+
+        example_coverage.each do |file_path, line_coverage|
+          accumulate_line_coverage(missed[file_path], line_coverage)
+        end
+      end
+
+      missed
+    end
+
+    # --- accessors used by specs ---------------------------------
+
+    def filtered_example_ids
+      @filtered_examples.keys
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def previous_snapshot_loaded?
+      !@previous_snapshot.nil?
+    end
+
+    private
+
+    # Read the config-level `track_env(*names)` accumulator,
+    # expand any wildcard patterns against the live ENV via
+    # EnvMatcher.expand (which raises ArgumentError on unsupported
+    # syntax - intentionally surfaces config errors at run start),
+    # and seed both `@config_tracked_env_names` (for the global
+    # mark-every-example branch in apply_env_filter_decisions) and
+    # `@tracked_env_names` (so the finalize snapshot includes every
+    # config-level key alongside per-example keys).
+    def register_config_tracked_env_names
+      patterns = @configuration.tracked_env_names
+      return if patterns.nil? || patterns.empty?
+
+      expanded = TestSift::Tracker::EnvMatcher.expand(patterns)
+      @config_tracked_env_names.merge(expanded)
+      @tracked_env_names.merge(expanded)
+    end
+
+    # Mark every previously-seen example for re-run. Called
+    # when a config-level env key flips between runs.
+    def mark_all_prev_examples(reason)
+      @previous_snapshot.all_examples.each_key do |example_id|
+        next if @filtered_examples.key?(example_id)
+
+        @filtered_examples[example_id] = reason
+      end
+    end
+
+    # Per-example env-changed mark. Walks @tracks_env,
+    # marks examples whose declared env set intersects invalidated.
+    # Additive vs other filter reasons (won't overwrite).
+    def mark_per_example_intersections(invalidated, reason)
+      @tracks_env.each do |example_id, envs|
+        next unless envs.intersect?(invalidated)
+        next if @filtered_examples.key?(example_id)
+
+        @filtered_examples[example_id] = reason
+      end
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def build_observers
+      @registry = TestSift::Tracker::ExampleRegistry.new
+      @graph = TestSift::Tracker::DependencyGraph.new
+      @coverage_adapter = TestSift::Tracker::CoverageAdapter.new(
+        root: @configuration.root, filters: @configuration.filters
+      )
+      @declared_globs = TestSift::Tracker::DeclaredGlobs.new(
+        root: @configuration.root, globs: @configuration.declared_globs
+      )
+      @whole_suite_invalidators = TestSift::Tracker::WholeSuiteInvalidators.new(
+        root: @configuration.root
+      )
+      @env_snapshot = TestSift::Tracker::EnvSnapshot.new
+      @new_file_detector = TestSift::Tracker::NewFileDetector.new(
+        root: @configuration.root, declared_globs: @configuration.declared_globs
+      )
+      @loaded_files_tracker = TestSift::Tracker::LoadedFilesTracker.new(
+        root: @configuration.root, enabled: @configuration.transitive_load_tracking
+      )
+      @storage_backend = build_storage_backend(@configuration.cache_path)
+    end
+
+    # Resolve the configured storage backend to a concrete instance.
+    # Delegates to {TestSift::Storage::Backend.build}, the single
+    # factory shared with the CLI sub-commands so `cache:info` /
+    # `explain` compose correctly with `storage_backend :sqlite`.
+    def build_storage_backend(cache_path)
+      TestSift::Storage::Backend.build(
+        cache_path: cache_path, configuration: @configuration
+      )
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def install_io_hooks
+      declared = @declared_globs
+      TestSift::Tracker::IOHooks.install(
+        root: @configuration.root,
+        filter: ->(path) { !declared.covers?(path) }
+      )
+    end
+
+    # Subscriber-install body. Idempotent via `@rails_observers_installed`
+    # so a re-call (e.g. eager path then late-bind firing on a slow Rails
+    # load) is a no-op. Shared between the eager and late-bind paths.
+    def install_rails_observers
+      return if rails_observers_installed?
+
+      require_relative 'rails/notifications'
+      require_relative 'rails/i18n_tracking'
+
+      declared = @declared_globs
+      filter = ->(path) { !declared.covers?(path) }
+      ar_paths = ar_schema_notifications_enabled? ? ar_schema_path_probes : []
+
+      TestSift::Rails::Notifications.install(
+        root: @configuration.root, filter: filter, ar_schema_paths: ar_paths
+      )
+      TestSift::Rails::I18nTracking.install(
+        root: @configuration.root, filter: filter
+      )
+
+      @rails_observers_installed = true
+    rescue StandardError => e
+      @configuration.logger.warn(
+        "testsift: Rails observer install failed (#{e.class}: #{e.message})"
+      )
+      @rails_observers_installed = false
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def uninstall_rails_observers
+      return unless rails_observers_installed?
+
+      TestSift::Rails::Notifications.uninstall
+      TestSift::Rails::I18nTracking.uninstall
+      @rails_observers_installed = false
+    rescue StandardError
+      @rails_observers_installed = false
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def rails_observers_installed?
+      defined?(@rails_observers_installed) && @rails_observers_installed == true
+    end
+
+    public :install_rails_observers, :rails_observers_installed?
+
+    # rubocop:disable Naming/AccessorMethodName
+    def set_rails_bucket(bucket)
+      return unless rails_observers_installed?
+
+      TestSift::Rails::Notifications.set_bucket(bucket)
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def clear_rails_bucket
+      return unless rails_observers_installed?
+
+      TestSift::Rails::Notifications.clear_bucket
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def ar_schema_notifications_enabled?
+      return false unless @configuration.respond_to?(:track_ar_schema_notifications?)
+
+      @configuration.track_ar_schema_notifications?
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def ar_schema_path_probes
+      %w[db/schema.rb db/structure.sql].each_with_object([]) do |rel, acc|
+        abs = File.expand_path(rel, @configuration.root)
+        acc << abs if File.file?(abs)
+      end
+    end
+
+    # Delegate to the legacy ::Coverage bootstrap if SimpleCov isn't
+    # already running. Matches TestSift.setup_coverage behavior so
+    # the two entry points agree on when to call ::Coverage.start
+    # AND on which Ruby Coverage modes are enabled.
+    def ensure_coverage_started
+      return if defined?(SimpleCov) && SimpleCov.running
+      return if ::Coverage.respond_to?(:running?) && ::Coverage.running?
+
+      ::Coverage.start(**configuration_coverage_modes)
+    rescue RuntimeError
+      # ::Coverage.start raises if already started on some Rubies
+      # without a running? predicate; safe to ignore.
+      nil
+    end
+
+    # Reads `coverage_modes` off the configuration when available
+    # (extended with `TestSift::Configuration`). Defaults to an
+    # empty Hash for stubbed-configuration unit tests so the splat
+    # `Coverage.start(**{})` keeps lines-only legacy behavior.
+    def configuration_coverage_modes
+      return {} unless @configuration.respond_to?(:coverage_modes_for_start)
+
+      @configuration.coverage_modes_for_start
+    end
+
+    # Under parallel_tests, each worker writes to its own per-worker
+    # cache dir (`testsift_cache/parallel_tests_N/`) but warm-run
+    # reads come from the MERGED top-level cache (`testsift_cache/`,
+    # one level up). Last-process finalize at exit purges the per-worker
+    # dirs, so only the merged snapshot survives between runs. Match
+    # 1.x Cache#load_cache_for_run's `File.dirname(cache_path) if
+    # parallel_tests?` behavior so warm runs under parallel_tests
+    # actually skip examples.
+    def load_previous_snapshot
+      read_backend = build_read_backend
+      read_backend.load_graph(schema_version: TestSift::Storage::Schema::CURRENT)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def build_read_backend
+      return @storage_backend unless @read_cache_path
+
+      build_storage_backend(@read_cache_path)
+    end
+
+    # On warm runs, skipped examples don't re-populate @all_examples,
+    # @all_files, or @graph - only newly-run examples do. Without
+    # seeding, the next save would drop the skipped examples'
+    # metadata + deps, and the following warm run would see them as
+    # "not previously seen" and force a cold re-run of the entire
+    # suite. Seed the three state buckets from the previous snapshot
+    # so newly-run examples overwrite and skipped examples carry
+    # forward.
+    #
+    # examples_coverage is NOT seeded here. A populated cache can
+    # carry a large examples_coverage map; eagerly materializing it
+    # at setup defeats LazySnapshot's whole point for the SQLite
+    # backend. The merge happens at build_snapshot time via
+    # merge_examples_coverage_with_previous instead.
+    def seed_state_from_previous(prev)
+      seed_all_examples_from_previous(prev)
+      seed_all_files_from_previous(prev)
+      seed_graph_from_previous(prev)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def seed_all_examples_from_previous(prev)
+      return unless prev.all_examples.is_a?(Hash)
+
+      prev.all_examples.each do |id, meta|
+        @all_examples[id] = meta
+      end
+    end
+
+    # prev.all_files is file-name-keyed; the engine's @all_files is
+    # abs-path-keyed (path_to_file_name round-trips via the root prefix).
+    #
+    # Re-applies the current filter list at seed time so users who
+    # add a filter mid-development see the carried-over file entries
+    # drop on the next run (instead of waiting for a cold run). The
+    # filter contract should hold for both fresh attributions
+    # (attribute_to_example) and prior-snapshot carry-forward —
+    # otherwise add_filter has split semantics and a freshly-added
+    # filter does not exclude already-cached paths.
+    def seed_all_files_from_previous(prev)
+      return unless prev.all_files.is_a?(Hash)
+
+      prev.all_files.each_value do |meta|
+        next unless meta.is_a?(Hash)
+
+        file_path = symbol_or_string(meta, :file_path)
+        next if file_path.nil?
+
+        file_name = symbol_or_string(meta, :file_name) || path_to_file_name(file_path)
+        next if filtered_by_current_filters?(file_name)
+
+        @all_files[file_path] = {
+          file_name: file_name,
+          file_path: file_path,
+          digest: symbol_or_string(meta, :digest)
+        }
+      end
+    end
+
+    # prev.dependency keys on example_id, values are Set<file_name>.
+    # Register in @graph via absolute paths so the on-disk shape
+    # (file_name) converts at save time via dependency_by_name.
+    #
+    # Drops paths matching the current filter list so previously-
+    # cached deps that the new filter excludes do not leak through
+    # the carry-forward seed path. Same rationale as
+    # seed_all_files_from_previous: the filter contract is one
+    # contract, applied uniformly across fresh + carry-forward
+    # attributions.
+    def seed_graph_from_previous(prev)
+      return unless prev.dependency.is_a?(Hash)
+
+      prev.dependency.each do |example_id, file_names|
+        paths = []
+        file_names.each do |name|
+          next if filtered_by_current_filters?(name)
+
+          paths << absolute_path(name)
+        end
+        @graph.register_example(example_id, paths)
+      end
+    end
+
+    # Helper: returns true if the file name matches any currently-
+    # configured filter. Mirrors the check site at
+    # `attribute_to_example` (engine.rb:770) so both fresh + carry-
+    # forward attributions converge on the same filter behavior.
+    def filtered_by_current_filters?(file_name)
+      @filter_decisions.fetch(file_name) do
+        @filter_decisions[file_name] = @configuration.filters.any? { |f| f.match?(file_name: file_name) }
+      end
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def compute_filter_decisions
+      prev = @previous_snapshot
+      return if prev.nil?
+
+      seed_registry_from_previous(prev)
+      change_set = compute_change_set(prev)
+      whole_suite = whole_suite_changed?(prev)
+
+      result = TestSift::Tracker::Filter.select(
+        graph: graph_from_previous(prev),
+        change_set: change_set,
+        registry: @registry,
+        whole_suite_invalidated: whole_suite,
+        all_example_ids: prev.all_examples.keys.to_set
+      )
+      @filtered_examples = result.transform_values { |reason| FILTER_REASON_STRINGS.fetch(reason) }
+    end
+
+    # Internal constant.
+    # @api private
+    SEED_STATUS_ORDER = %i[interrupted flaky failed pending].freeze
+    private_constant :SEED_STATUS_ORDER
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def seed_registry_from_previous(prev)
+      SEED_STATUS_ORDER.each do |status|
+        ids = prev.send(:"#{status}_examples")
+        ids.each { |id| seed_registry_entry(id, status, prev.all_examples[id] || {}) }
+      end
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def seed_registry_entry(id, status, metadata)
+      return if @registry.registered?(id)
+
+      @registry.register(id, metadata: metadata)
+      @registry.update_status(id, status)
+    end
+
+    # Rebuild a DependencyGraph from the previous Snapshot so Filter
+    # can intersect its cached dependency sets with the change_set.
+    def graph_from_previous(prev)
+      graph = TestSift::Tracker::DependencyGraph.new
+      prev.dependency.each { |id, paths| graph.register_example(id, paths) }
+      graph
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def compute_change_set(prev)
+      changed = Set.new
+      prev.all_files.each_value do |file_meta|
+        file_name = symbol_or_string(file_meta, :file_name)
+        cached_digest = symbol_or_string(file_meta, :digest)
+        next if file_name.nil? || cached_digest.nil?
+
+        current_digest = current_file_digest(file_name)
+        changed << file_name if current_digest.nil? || current_digest != cached_digest
+      end
+
+      new_files = @new_file_detector.new_files(
+        known_paths: prev.all_files.keys.to_set.to_set { |k| absolute_path(k) }
+      )
+      new_files.each { |input| changed << path_to_file_name(input.path) }
+      changed
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def whole_suite_changed?(prev)
+      wsi_prev = prev.wsi_snapshot if prev.respond_to?(:wsi_snapshot)
+      @whole_suite_invalidators.invalidated?(wsi_prev) ||
+        @loaded_files_tracker.boot_set_invalidated?(prev.boot_set)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def current_file_digest(file_name)
+      TestSift::Tracker::FileDigest.compute(absolute_path(file_name))
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def record_coverage_delta(example_id, before, after)
+      entry = @examples_coverage[example_id] ||= {}
+
+      (before.keys | after.keys).each do |path|
+        b_lines = before[path]
+        a_lines = after[path]
+        next if b_lines == a_lines
+
+        file_entry = entry[path] ||= {}
+        accumulate_delta(file_entry, b_lines, a_lines)
+      end
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def accumulate_delta(file_entry, before_lines, after_lines)
+      length = (after_lines || before_lines || []).length
+      length.times do |i|
+        delta = line_delta(before_lines && before_lines[i], after_lines && after_lines[i])
+        file_entry[i] = delta if delta
+      end
+    end
+
+    # Returns the positive coverage delta for one line, or nil if the
+    # line isn't a delta worth recording (non-executable, identical,
+    # or a stale-going-backward entry).
+    def line_delta(before, after)
+      return nil if after.nil? || before == after
+
+      delta = after - (before || 0)
+      delta.positive? ? delta : nil
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def accumulate_line_coverage(accumulator, line_coverage)
+      line_coverage.each do |line_key, strength|
+        index = line_key.to_i
+        accumulator[index] += strength || 0
+      end
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def attribute_to_example(example_id, inputs)
+      paths = []
+      inputs.each do |input|
+        file_name = attributed_file_name(input.path)
+        next if file_name.nil?
+
+        paths << input.path
+        entry = @all_files[input.path]
+        next if entry && entry[:digest] == input.digest && entry[:file_name] == file_name
+
+        @all_files[input.path] = { file_name: file_name, file_path: input.path, digest: input.digest }
+      end
+      @graph.register_example(example_id, paths)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def attributed_file_name(path)
+      file_name = path_to_file_name(path)
+      file_name unless filtered_by_current_filters?(file_name)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def record_execution_result(example_id, result)
+      return unless @all_examples.key?(example_id)
+
+      @all_examples[example_id][:execution_result] = result.dup
+    end
+
+    # Ports the 1.x flaky-detection contract: an example transitions
+    # into `:flaky` when it (a) failed on the previous run and passes
+    # on this run (the canonical "intermittent" signal) OR (b) was
+    # already flaky on the previous run, regardless of this run's
+    # outcome (sticky once detected). Mirrors 1.x's
+    # `ReportGenerator#generate_flaky_examples_report` which iterated
+    # `prev_failed | prev_flaky` and registered the example as flaky
+    # unless the prev_failed branch failed again this run.
+    def flaky_history?(id)
+      previously_failed?(id) || previously_flaky?(id)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def previously_failed?(id)
+      @previous_snapshot&.failed_examples&.include?(id)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def previously_flaky?(id)
+      @previous_snapshot&.flaky_examples&.include?(id)
+    end
+
+    # Resolve one glob against the project root into a Set of
+    # `:declared`-kind Inputs. Walks via Dir.glob
+    # (FNM_PATHNAME+FNM_EXTGLOB like DeclaredGlobs so user muscle
+    # memory works identically) and digests each hit with SHA256.
+    # Unreadable files are skipped silently - graceful degradation.
+    # Memoized per distinct glob string so N examples declaring the
+    # same glob pay the filesystem walk cost exactly once.
+    def resolved_glob_inputs(glob)
+      @resolved_glob_cache ||= {}
+      @resolved_glob_cache[glob] ||= walk_one_glob(glob)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def walk_one_glob(glob)
+      inputs = Set.new
+      root = @configuration.root
+      Dir.glob(glob, File::FNM_PATHNAME | File::FNM_EXTGLOB, base: root).each do |rel|
+        abs = File.expand_path(rel, root)
+        next unless abs.start_with?("#{root}/") && File.file?(abs)
+
+        digest = tracks_file_digest(abs)
+        next if digest.nil?
+
+        inputs << TestSift::Tracker::Input.for_file(
+          path: abs, kind: :declared, digest: digest, root: root
+        )
+      end
+      inputs
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def tracks_file_digest(path)
+      TestSift::Tracker::FileDigest.compute(path)
+    end
+
+    # Materialize the per-example tracks-file Input set. Returns an
+    # empty Set when the example has no `tracks: files:` metadata,
+    # keeping the downstream union cheap for the 99% case.
+    def per_example_tracks_inputs(example_id)
+      set = @tracks_files[example_id]
+      set.nil? || set.empty? ? Set.new : set.dup
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def absolute_path(file_name)
+      @absolute_paths[file_name] ||= -File.expand_path(file_name.to_s.sub(%r{^/}, ''), @configuration.root)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def path_to_file_name(abs_path)
+      @file_names[abs_path] ||= begin
+        root_prefix = "#{@configuration.root}/"
+        -(abs_path.start_with?(root_prefix) ? "/#{abs_path[root_prefix.length..]}" : abs_path)
+      end
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def symbol_or_string(hash, key)
+      return hash[key] if hash.key?(key)
+
+      hash[key.to_s]
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end