rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/example.rb

@@ -1,22 +1,147 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # 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
-    module_function
+    # 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
 
-    def from(example)
-      data = {
-        example_group: example.example_group.name,
+    # 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(&:formatted_inclusion_location)
-      }.merge(example_location(example))
+          .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) }
 
-      data.merge(example_id: Digest::MD5.hexdigest(data.to_json))
+      "#<rspec-tracer unnamed example #{unnamed_siblings.index(example)}>"
     end
 
-    def example_location(example)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.example_location(example)
       metadata = example.metadata
 
       location = {
@@ -34,7 +159,9 @@ module RSpecTracer
       location.merge(example_rerun_location(example.example_group.parent_groups))
     end
 
-    def example_rerun_location(example_groups)
+    # 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
 
@@ -47,12 +174,15 @@ module RSpecTracer
       end
     end
 
-    def location_file_name(rspec_file_name)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.location_file_name(rspec_file_name)
       file_path = RSpecTracer::SourceFile.file_path(rspec_file_name)
 
       RSpecTracer::SourceFile.file_name(file_path)
     end
 
-    private_class_method :example_location, :example_rerun_location, :location_file_name
+    private_class_method :digest_identity, :unnamed?, :unnamed_description,
+                         :example_location, :example_rerun_location, :location_file_name
   end
 end

data/lib/rspec_tracer/filter.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # Internal Filter — see {RSpecTracer} 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
@@ -25,16 +38,24 @@ module RSpecTracer
       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 {RSpecTracer} for the user-facing surface.
+  # @api private
   class ArrayFilter < RSpecTracer::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)
@@ -43,24 +64,38 @@ module RSpecTracer
       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 {RSpecTracer} for the user-facing surface.
+  # @api private
   class BlockFilter < RSpecTracer::Filter
+    # Internal method on the tracer pipeline.
+    # @api private
     def match?(source_file)
       @filter.call(source_file)
     end
   end
 
+  # Internal RegexFilter — see {RSpecTracer} for the user-facing surface.
+  # @api private
   class RegexFilter < RSpecTracer::Filter
+    # Internal method on the tracer pipeline.
+    # @api private
     def match?(source_file)
       source_file[:file_name] =~ @filter
     end
   end
 
+  # Internal StringFilter — see {RSpecTracer} for the user-facing surface.
+  # @api private
   class StringFilter < RSpecTracer::Filter
+    # Internal method on the tracer pipeline.
+    # @api private
     def match?(source_file)
       source_file[:file_name].include?(@filter)
     end

data/lib/rspec_tracer/line_stub.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # 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/rspec_tracer 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).
+  #
+  # `def self.x` per feedback_mutation_friendly_modules so future
+  # mutation gating maps to the singleton form.
+  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/rspec_tracer/load_config.rb

@@ -8,8 +8,8 @@ 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, &block|`) the
-# first time any configurer runs. `load_default_config` is
+# (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 `RSpecTracer.add_filter` etc. No second install step is
 # needed here.

data/lib/rspec_tracer/logger.rb

@@ -1,23 +1,38 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # Internal Logger — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  #
+  # Internal logger; thin wrapper around `puts` gated on numeric log
+  # level. Exposed via `RSpecTracer.logger`.
   class Logger
+    # Internal method on the tracer pipeline.
+    # @api private
     def initialize(log_level)
       @log_level = log_level
     end
 
+    # Internal method on the tracer pipeline.
+    # @api private
     def debug(message)
       puts message if @log_level == 1
     end
 
+    # Internal method on the tracer pipeline.
+    # @api private
     def info(message)
       puts message if @log_level.between?(1, 2)
     end
 
+    # Internal method on the tracer pipeline.
+    # @api private
     def warn(message)
       puts message if @log_level.between?(1, 3)
     end
 
+    # Internal method on the tracer pipeline.
+    # @api private
     def error(message)
       puts message if @log_level.between?(1, 4)
     end

data/lib/rspec_tracer/rails/README.md

@@ -0,0 +1,78 @@
+# Rails integration
+
+Loaded by `require 'rspec_tracer/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
+
+- **`RSpecTracer::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 `.rspec-tracer`; opt out per category via
+  `track_rails_defaults except: [:views, :locales]`.
+- **`RSpecTracer::Rails::Railtie`** - only loaded when
+  `defined?(::Rails::Railtie)`. Registers a single `rspec_tracer.setup`
+  initializer that logs a confirmation line when Rails boots.
+- **`RSpecTracer::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
+  `RSpecTracer.rails?` is true. Emits `:template` Inputs for observed
+  template renders and `:notification` Inputs for schema files on the
+  first AR query per example.
+- **`RSpecTracer::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
+
+`RSpecTracer.rails?` returns true when `::Rails::VERSION` is defined at
+the time `RSpecTracer.start` runs. The flag is computed once during
+`initial_setup`; subsequent Rails loads do not flip it.
+
+## Zero-cost when Rails is absent
+
+`require 'rspec_tracer/rails'` loads Preset unconditionally and skips
+the Railtie via `defined?(::Rails::Railtie)`. Notifications and
+I18nTracking are required lazily by `Engine.setup` only when
+`RSpecTracer.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
+RSpecTracer.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.

data/lib/rspec_tracer/rails/i18n_tracking.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative '../tracker/file_digest'
+require_relative '../tracker/input'
+require_relative 'notifications'
+
+module RSpecTracer
+  # Internal Rails — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Rails
+    # I18n backend observer. Covers custom backends (Redis-backed,
+    # DB-backed, Chain) that bypass YAML.load_file and would otherwise
+    # miss the IOHooks YAML hook.
+    #
+    # Mechanism: Module#prepend onto ::I18n::Backend::Base - every
+    # backend subclass's load_translations resolves through the hook,
+    # even when the subclass overrides and super-calls Base. Backends
+    # that never super-call Base#load_translations fall through the
+    # hook, but the common backends (Simple, Chain, Cascade) all do.
+    #
+    # Shares Notifications' thread-local bucket so Engine.setup opens
+    # and clears one bucket per example that covers both observer
+    # families. Engine harvests `bucket.values` at example_finished.
+    #
+    # Graceful degradation:
+    # - install no-ops if ::I18n::Backend::Base is absent (tracer
+    #   boot survives even in weird I18n-free app graphs).
+    # - Every record call swallows StandardError (CLAUDE.md) - a
+    #   digest failure or bucket-shape surprise never propagates into
+    #   the user's test run.
+    class I18nTracking
+      class << self
+        # Internal attribute.
+        # @api private
+        attr_reader :root
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def install(root:, filter: ->(_path) { true })
+          @root = File.expand_path(root)
+          @root_prefix = "#{@root}/"
+          @filter = filter
+          @prepended = prepend_backend_hook
+
+          self
+        end
+
+        # Prepended modules cannot be removed from the ancestry chain
+        # (Ruby has no public API), mirroring IOHooks.uninstall. Every
+        # hook entry point fast-rejects on @root_prefix nil once
+        # install state clears, so post-uninstall the hook is a no-op.
+        def uninstall
+          @root = nil
+          @root_prefix = nil
+          @filter = nil
+          @prepended = false
+          self
+        end
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def installed?
+          !@root_prefix.nil?
+        end
+
+        # Called from LoadTranslationsHook for every filename passed
+        # to I18n::Backend::Base#load_translations. Array form keeps
+        # the hook a single call site.
+        def record_translations(filenames)
+          return nil if @root_prefix.nil?
+
+          Array(filenames).each { |path| record_translation(path) }
+          nil
+        end
+
+        # Pure-logic entry point. Same fast-reject ladder as
+        # Notifications#record_template. Emits :notification kind
+        # so the I18n source is distinguishable from template events
+        # in downstream reporters. The ladder is longer than rubocop's
+        # perceived-complexity threshold by design - each guard is a
+        # cheap fast-reject.
+        # rubocop:disable Metrics/PerceivedComplexity
+        def record_translation(path)
+          return nil if @root_prefix.nil?
+
+          bucket = Notifications.current_bucket
+          return nil if bucket.nil?
+          return nil unless path.is_a?(String) || path.respond_to?(:to_s)
+
+          path_str = path.to_s
+          return nil unless path_str.start_with?(@root_prefix)
+          return nil unless @filter.call(path_str)
+
+          identity = "notification:#{path_str[@root_prefix.length..]}"
+          return nil if bucket.key?(identity)
+
+          digest = Tracker::FileDigest.compute(path_str)
+          return nil if digest.nil?
+
+          bucket[identity] = Tracker::Input.for_file(
+            path: path_str, kind: :notification, digest: digest, root: @root
+          )
+        rescue StandardError
+          nil
+        end
+        # rubocop:enable Metrics/PerceivedComplexity
+
+        private
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def prepend_backend_hook
+          return false unless defined?(::I18n::Backend::Base)
+
+          ::I18n::Backend::Base.prepend(LoadTranslationsHook)
+          true
+        rescue StandardError
+          false
+        end
+      end
+
+      # Prepended onto I18n::Backend::Base. Every subclass's
+      # load_translations ultimately resolves through here via super.
+      # Intercepts the filename list, delegates recording to the
+      # singleton, and forwards to the real implementation.
+      # @api private
+      module LoadTranslationsHook
+        # Internal method on the tracer pipeline.
+        # @api private
+        def load_translations(*filenames)
+          RSpecTracer::Rails::I18nTracking.record_translations(filenames)
+          super
+        end
+      end
+    end
+  end
+end