testsift 0.0.1

data/lib/testsift/example.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module TestSift
+  # Builds the identity-hash payload (`:example_id`-keyed Hash) that
+  # RSpec::RunnerHook attaches to every example pre-run.
+  #
+  # == Identity stability contract
+  #
+  # `example_id` is the MD5 of a stable subset of the payload:
+  # `example_group` (the describe block's *description* string),
+  # `description`, `full_description`, `shared_group` (inclusion
+  # locations with the trailing line number stripped), and
+  # `file_name`. The contract, in one line: *rename = new identity;
+  # restructure = same identity.*
+  #
+  # Identity is PRESERVED when:
+  # - blank lines or comments are added/removed around the example
+  # - examples are reordered within a describe block (named
+  #   examples only - see "Unnamed examples" below)
+  # - a sibling describe / example in the same file is renamed
+  # - metadata changes (`skip:`, tags, `tracks: { ... }`) - the
+  #   spec-file digest still triggers the re-run and status history
+  #   is kept
+  # - the example body or its hooks (`before`, `let`) are edited -
+  #   again, the file digest triggers the re-run
+  #
+  # Identity CHANGES (one cold "No cache" run) when:
+  # - the file is renamed or moved
+  # - the `describe` / `it` / shared-example name is changed
+  # - the example moves to a different describe block
+  #
+  # == Unnamed examples (`it { }`, `specify { }`, `example { }`)
+  #
+  # An example with no description string has no stable name to hash,
+  # and identity must be computed pre-run (for the filter decision),
+  # before RSpec generates a matcher-derived description. The only
+  # line-independent signal RSpec exposes pre-run is position, so an
+  # unnamed example's identity is derived from its ordinal among the
+  # *unnamed* examples of its group. (RSpec's `description` for an
+  # unnamed example is the line-bearing `"example at <path>:<line>"`
+  # fallback, which would otherwise leak the line number straight
+  # back into the digest - issue #210.)
+  #
+  # For unnamed examples the contract above is amended: identity is
+  # still PRESERVED across blank-line / comment edits, sibling
+  # renames, and adding or removing *named* siblings - but it CHANGES
+  # when the unnamed examples are reordered, or one is inserted or
+  # removed ahead of it. Give an example an explicit description
+  # (`it 'does X' do`) for a fully reorder-stable identity.
+  #
+  # `line_number` / `rerun_file_name` / `rerun_line_number` stay in
+  # the returned Hash for the reporter + `explain` location columns,
+  # but are DELIBERATELY EXCLUDED from the digest - a no-op edit that
+  # shifts line numbers must not invalidate the cache. `example_group`
+  # uses `example_group.description` (the user's string) rather than
+  # `example_group.name`: RSpec's generated class name carries a
+  # load-order-dependent `_2` / `_3` suffix when two files share a
+  # describe name, which would otherwise flip the id across runs.
+  #
+  # Helpers are `def self.x` + `private_class_method` so mutant
+  # attributes mutations through the singleton call path.
+  module Example
+    # Identity-keyed cache of `<example_group> => Array<unnamed sibling>`
+    # populated lazily by `unnamed_description`. A group with N unnamed
+    # examples computes the sibling list once per group rather than N
+    # times. Memory is bounded by the live group set (RSpec retains
+    # those for the run anyway).
+    @unnamed_siblings_cache = {}.compare_by_identity
+
+    # Builds the identity payload for one RSpec example. The MD5 is
+    # taken over the stability-contract subset (see `digest_identity`
+    # for the named-vs-unnamed split); `line_number` / `rerun_*` ride
+    # along in the returned Hash for the reporters but never enter the
+    # digest. See the module comment for the full stability contract.
+    # @api private
+    def self.from(example)
+      location = example_location(example)
+      identity = {
+        example_group: example.example_group.description,
+        description: example.description,
+        full_description: example.full_description,
+        shared_group: example.metadata[:shared_group_inclusion_backtrace]
+          .map { |frame| frame.formatted_inclusion_location.sub(/:\d+\z/, '') },
+        file_name: location[:file_name]
+      }
+
+      identity
+        .merge(location)
+        .merge(example_id: Digest::MD5.hexdigest(digest_identity(example, identity).to_json))
+    end
+
+    # The Hash actually fed to the MD5. For a named example this is
+    # `identity` unchanged - byte-identical to the pre-#210 digest.
+    # For an unnamed example (`it { }` / `specify { }` / `example { }`)
+    # RSpec's `description` is the line-bearing location fallback
+    # `"example at <path>:<line>"`, so `description` is swapped for a
+    # line-independent positional discriminator before hashing. The
+    # returned/stored payload still carries RSpec's `description` /
+    # `full_description` untouched - only the digest input differs.
+    # @api private
+    def self.digest_identity(example, identity)
+      return identity unless unnamed?(example)
+
+      identity.merge(description: unnamed_description(example))
+    end
+
+    # True when the example has no explicit description string. RSpec's
+    # raw `metadata[:description]` is `""` for `it { }` / `specify { }`
+    # / `example { }`; the `description` *method* would instead return
+    # the line-bearing `"example at <path>:<line>"` fallback, so the
+    # raw metadata value is what cleanly tells named from unnamed.
+    # @api private
+    def self.unnamed?(example)
+      example.metadata[:description].to_s.strip.empty?
+    end
+
+    # Line-independent identity discriminator for an unnamed example:
+    # its 0-based ordinal among the *unnamed* examples of its group.
+    # Stable across blank-line / comment edits and across adding or
+    # renaming *named* siblings; changes only when the unnamed examples
+    # are reordered or one is inserted / removed ahead of it (the
+    # documented carve-out - see the module comment). Closes the
+    # remaining #196 gap reported in #210.
+    #
+    # The unnamed-siblings list is memoized per example_group object,
+    # so a group with N unnamed examples computes the list once, not N
+    # times. The discriminator string takes a Ruby-inspect-style
+    # `#<...>` form to make spoofing implausible - and even if a user
+    # description literally matched, full_description would still
+    # differ between the unnamed example (`"<group> "`) and the named
+    # one (`"<group> #<...>"`), so no real digest collision is
+    # possible.
+    # @api private
+    def self.unnamed_description(example)
+      group = example.example_group
+      unnamed_siblings = @unnamed_siblings_cache[group] ||=
+        group.examples.select { |sibling| unnamed?(sibling) }
+
+      "#<testsift unnamed example #{unnamed_siblings.index(example)}>"
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.example_location(example)
+      metadata = example.metadata
+
+      location = {
+        file_name: location_file_name(metadata[:file_path]),
+        line_number: metadata[:line_number]
+      }
+
+      if metadata[:file_path] == metadata[:rerun_file_path]
+        return location.merge(
+          rerun_file_name: location[:file_name],
+          rerun_line_number: location[:line_number]
+        )
+      end
+
+      location.merge(example_rerun_location(example.example_group.parent_groups))
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.example_rerun_location(example_groups)
+      example_groups.each do |example_group|
+        metadata = example_group.metadata
+
+        next unless metadata[:file_path] == metadata[:rerun_file_path]
+
+        return {
+          rerun_file_name: location_file_name(metadata[:file_path]),
+          rerun_line_number: metadata[:line_number]
+        }
+      end
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.location_file_name(rspec_file_name)
+      file_path = TestSift::SourceFile.file_path(rspec_file_name)
+
+      TestSift::SourceFile.file_name(file_path)
+    end
+
+    private_class_method :digest_identity, :unnamed?, :unnamed_description,
+                         :example_location, :example_rerun_location, :location_file_name
+  end
+end

data/lib/testsift/filter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module TestSift
+  # Internal Filter — see {TestSift} for the user-facing surface.
+  # @api private
+  #
+  # Internal dispatch shim for the user-facing `add_filter` /
+  # `add_coverage_filter` DSL. The user passes a String / Regexp /
+  # Proc / Array; `Filter.register` wraps it in the matching subclass
+  # so the engine can call a uniform `#match?(source_file)`.
+  class Filter
+    # Internal attribute.
+    # @api private
+    attr_reader :filter
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.register(filter)
+      return filter if filter.is_a?(Filter)
+
+      filter_class(filter).new(filter)
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.filter_class(filter)
+      case filter
+      when String
+        StringFilter
+      when Regexp
+        RegexFilter
+      when Proc
+        BlockFilter
+      when Array
+        ArrayFilter
+      else
+        raise ArgumentError, 'Unknow filter'
+      end
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def initialize(filter)
+      @filter = filter
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def match?(_source_file)
+      raise "#{self.class.name}#match? is not intended for direct use"
+    end
+  end
+
+  # Internal ArrayFilter — see {TestSift} for the user-facing surface.
+  # @api private
+  class ArrayFilter < TestSift::Filter
+    # Internal method on the tracer pipeline.
+    # @api private
+    def initialize(filters)
+      filter_list = filters.each_with_object([]) do |filter, list|
+        list << Filter.register(filter)
+      end
+
+      super(filter_list)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def match?(source_file)
+      @filter.any? { |filter| filter.match?(source_file) }
+    end
+  end
+
+  # Internal BlockFilter — see {TestSift} for the user-facing surface.
+  # @api private
+  class BlockFilter < TestSift::Filter
+    # Internal method on the tracer pipeline.
+    # @api private
+    def match?(source_file)
+      @filter.call(source_file)
+    end
+  end
+
+  # Internal RegexFilter — see {TestSift} for the user-facing surface.
+  # @api private
+  class RegexFilter < TestSift::Filter
+    # Internal method on the tracer pipeline.
+    # @api private
+    def match?(source_file)
+      source_file[:file_name] =~ @filter
+    end
+  end
+
+  # Internal StringFilter — see {TestSift} for the user-facing surface.
+  # @api private
+  class StringFilter < TestSift::Filter
+    # Internal method on the tracer pipeline.
+    # @api private
+    def match?(source_file)
+      source_file[:file_name].include?(@filter)
+    end
+  end
+end

data/lib/testsift/line_stub.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module TestSift
+  # Per-engine line-stub builder for files that need a synthetic
+  # all-nil-but-executable-lines coverage array. Used by
+  # `Reporters::CoverageJsonReporter` when a tracked file is in
+  # `coverage_tracked_files` but has no recorded coverage (file never
+  # loaded during this run).
+  #
+  # Lives at the top level of lib/testsift so the per-engine
+  # branches sit outside the tracker_coverage_gate's
+  # 100%-line+branch contract (the JRuby branch cannot be exercised
+  # on MRI; cross-engine coverage rollup would require fork-per-engine
+  # CI work that isn't justified for stub-line generation).
+  #
+  # Methods use `def self.x` (not module_function) so future mutation
+  # gating maps to the singleton form -- module_function attaches
+  # methods to an anonymous singleton that mutant cannot observe.
+  module LineStub
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.for(file_path)
+      case RUBY_ENGINE
+      when 'ruby'
+        ruby(file_path)
+      when 'jruby'
+        jruby(file_path)
+      else
+        File.foreach(file_path).map { nil }
+      end
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.ruby(file_path)
+      lines = File.foreach(file_path).map { nil }
+      iseqs = [::RubyVM::InstructionSequence.compile_file(file_path)]
+      until iseqs.empty?
+        iseq = iseqs.pop
+        iseq.trace_points.each { |line_number, type| lines[line_number - 1] = 0 if type == :line }
+        iseq.each_child { |child| iseqs << child }
+      end
+      lines
+    end
+
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.jruby(file_path)
+      lines = File.foreach(file_path).map { nil }
+      root_node = ::JRuby.parse(File.read(file_path, encoding: 'UTF-8'))
+      visitor = org.jruby.ast.visitor.NodeVisitor.impl do |_name, node|
+        if node.newline?
+          ln = node.respond_to?(:position) ? node.position.line : node.line
+          lines[ln] = 0
+        end
+        node.child_nodes.each { |child| child&.accept(visitor) }
+      end
+      root_node.accept(visitor)
+      lines
+    end
+  end
+end

data/lib/testsift/load_config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'configuration'
+TestSift.extend TestSift::Configuration
+
+require_relative 'load_default_config'
+require_relative 'load_global_config'
+require_relative 'load_local_config'
+
+# NOTE: `Configuration#configure` installs the public DSL wrappers
+# (alias `_name` + redefine `name` to forward `|*args, **kwargs, &block|`)
+# the first time any configurer runs. `load_default_config` is
+# unconditional, so the wrappers are guaranteed to exist before anyone
+# can call `TestSift.add_filter` etc. No second install step is
+# needed here.

data/lib/testsift/load_default_config.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+TestSift.configure do
+  log_level :info
+  fail_on_duplicates true
+
+  filters.clear
+  add_filter %w[
+    /vendor/bundle/
+    /lib/testsift/
+    /lib/testsift.rb
+    /usr/local/lib/ruby/
+    /usr/local/bundle/
+    /opt/hostedtoolcache/
+    /.rbenv/versions/
+    /.asdf/installs/ruby/
+    /.rvm/
+    /testsift_cache/
+    /testsift_coverage/
+    /testsift_report/
+    testsift.lock
+  ].freeze
+
+  coverage_filters.clear
+  add_coverage_filter %w[
+    /autotest/
+    /features/
+    /spec/
+    /test/
+    /vendor/bundle/
+    /lib/testsift/
+    /lib/testsift.rb
+    /usr/local/lib/ruby/
+    /usr/local/bundle/
+    /opt/hostedtoolcache/
+    /.rbenv/versions/
+    /.asdf/installs/ruby/
+    /.rvm/
+    /testsift_cache/
+    /testsift_coverage/
+    /testsift_report/
+    testsift.lock
+  ].freeze
+end
+# rubocop:enable Metrics/BlockLength

data/lib/testsift/load_global_config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'etc'
+
+# Resolve the user's home directory without raising at gem-load time. Each
+# primitive (Dir.home, Etc.getpwuid.dir, File.expand_path("~user")) can raise
+# ArgumentError when HOME is unset and the passwd database has no matching
+# entry (common in minimal containers and CI images). Graceful degradation:
+# if none resolves, skip global config entirely rather than aborting boot.
+home_dir = begin
+  Dir.home
+rescue ArgumentError
+  nil
+end
+
+home_dir ||= begin
+  Etc.getpwuid.dir
+rescue ArgumentError
+  nil
+end
+
+user = ENV.fetch('USER', nil)
+home_dir ||= begin
+  File.expand_path("~#{user}") if user
+rescue ArgumentError
+  nil
+end
+
+if home_dir
+  global_config_path = File.join(home_dir, '.testsift')
+
+  load global_config_path if File.exist?(global_config_path)
+end

data/lib/testsift/load_local_config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+config_path = Pathname.new(TestSift.root)
+
+loop do
+  filename = config_path.join('.testsift')
+
+  if filename.exist?
+    load filename
+
+    break
+  end
+
+  config_path, = config_path.split
+
+  break if config_path.root?
+end

data/lib/testsift/logger.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TestSift
+  # Internal Logger — see {TestSift} for the user-facing surface.
+  # @api private
+  #
+  # Internal logger; thin wrapper around `IO#puts` gated on numeric
+  # log level. Exposed via `TestSift.logger`.
+  class Logger
+    class << self
+      # Process-wide default destination for loggers constructed
+      # without an explicit `out:`. `nil` (the norm) means `$stdout`,
+      # which normal `rspec` runs rely on. The `testsift` binary
+      # sets this to its stderr BEFORE booting the tracer library, so
+      # loggers constructed while the project's `.testsift` config
+      # loads (e.g. by the 1.x deprecation shims, or recreated after a
+      # config `log_level` call resets the memoized instance) already
+      # bind to stderr and machine-readable stdout (`blast-radius
+      # --json`) stays free of diagnostics. See {TestSift::CLI}.
+      #
+      # @return [IO, nil]
+      # @api private
+      attr_accessor :default_out
+    end
+
+    # @param log_level [Integer] numeric level (Configuration::LOG_LEVEL)
+    # @param out [IO, nil] destination stream. Falls back to
+    #   {Logger.default_out} when nil, then to `$stdout`.
+    # @api private
+    def initialize(log_level, out: nil)
+      @log_level = log_level
+      @out = out || self.class.default_out || $stdout
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def debug(message)
+      @out.puts message if @log_level == 1
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def info(message)
+      @out.puts message if @log_level.between?(1, 2)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def warn(message)
+      @out.puts message if @log_level.between?(1, 3)
+    end
+
+    # Internal method on the tracer pipeline.
+    # @api private
+    def error(message)
+      @out.puts message if @log_level.between?(1, 4)
+    end
+  end
+end

data/lib/testsift/rails/README.md

@@ -0,0 +1,78 @@
+# Rails integration
+
+Loaded by `require 'testsift/rails'`. Exposes the Rails preset, the
+Rails-side observer family, and a Railtie that integrates with the Rails
+lifecycle when Rails is present in the process.
+
+## Surface
+
+- **`TestSift::Rails::Preset`** - closed-enum glob set covering the
+  Coverage-invisible Rails surface (views, helpers, locales, config
+  YAML, schema, factories, fixtures). Opt in via `track_rails_defaults`
+  in `.testsift`; opt out per category via
+  `track_rails_defaults except: [:views, :locales]`.
+- **`TestSift::Rails::Railtie`** - only loaded when
+  `defined?(::Rails::Railtie)`. Registers a single `testsift.setup`
+  initializer that logs a confirmation line when Rails boots.
+- **`TestSift::Rails::Notifications`** - ActiveSupport::Notifications
+  observer for the render_template / render_partial / render_collection
+  events (ActionView) plus an opt-in sql.active_record subscriber for
+  narrow schema attribution. Installed by `Engine.setup` when
+  `TestSift.rails?` is true. Emits `:template` Inputs for observed
+  template renders and `:notification` Inputs for schema files on the
+  first AR query per example.
+- **`TestSift::Rails::I18nTracking`** - prepends onto
+  `::I18n::Backend::Base#load_translations` so every I18n backend
+  (including custom Redis/DB/Chain backends that bypass
+  `YAML.load_file`) emits `:notification` Inputs for the translation
+  files it loads.
+
+## Detection
+
+`TestSift.rails?` returns true when `::Rails::VERSION` is defined at
+the time `TestSift.start` runs. The flag is computed once during
+`initial_setup`; subsequent Rails loads do not flip it.
+
+## Zero-cost when Rails is absent
+
+`require 'testsift/rails'` loads Preset unconditionally and skips
+the Railtie via `defined?(::Rails::Railtie)`. Notifications and
+I18nTracking are required lazily by `Engine.setup` only when
+`TestSift.rails?` is truthy. A pure-Ruby suite that accidentally
+requires the file never pays for Rails-specific code.
+
+## Narrow schema attribution (opt-in)
+
+By default, `track_rails_defaults` attaches `db/schema.rb` and
+`db/structure.sql` to every example via the Preset's `:schema`
+declared-glob - a conservative whole-suite signal. Teams that want
+schema changes to re-run only examples that actually touched AR can
+opt into an `sql.active_record` subscriber:
+
+```ruby
+TestSift.configure do
+  track_rails_defaults except: [:schema]
+  track_ar_schema_notifications
+end
+```
+
+On the first `sql.active_record` event inside an example, the
+subscriber emits `:notification` Inputs for `db/schema.rb` and
+`db/structure.sql` if they exist under the project root, then
+short-circuits for the remainder of that example. A non-DB-touching
+example never sees the schema inputs and is not re-run on schema edits.
+
+Leaving `:schema` in `track_rails_defaults` while also enabling the
+subscriber is a no-op in terms of the re-run set - declared-glob
+dominates at graph registration.
+
+## Components
+
+- **Preset + detection + Railtie scaffold.**
+- **Notifications + I18nTracking observers**, the
+  `track_ar_schema_notifications` opt-in DSL, and `Engine.setup`
+  wiring. Factory and fixture coverage ride the existing
+  `LoadedFilesTracker` / `YAML.load_file` hook surface.
+- **Integration coverage** against the reference Rails app
+  (`spec/fixtures/rails_app/`) verifying the full "change X -> Y
+  re-runs" behavior matrix.