rspec-tracer 1.2.2 → 2.0.0.pre.1

data/lib/rspec_tracer/example.rb

@@ -1,10 +1,19 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # Builds the identity-hash payload (`:example_id`-keyed Hash) that
+  # RSpec::RunnerHook attaches to every example pre-run.
+  #
+  # All methods declared `def self.x` + `private_class_method` for
+  # the private helpers per feedback_mutation_friendly_modules:
+  # mutant maps tests to the singleton form. Public API
+  # (`Example.from`) is the only call site `runner_hook.rb` + the
+  # runner-hook spec drive; the three private helpers stay reachable
+  # only from `from` itself.
   module Example
-    module_function
-
-    def from(example)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.from(example)
       data = {
         example_group: example.example_group.name,
         description: example.description,
@@ -16,7 +25,9 @@ module RSpecTracer
       data.merge(example_id: Digest::MD5.hexdigest(data.to_json))
     end
 
-    def example_location(example)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.example_location(example)
       metadata = example.metadata
 
       location = {
@@ -34,7 +45,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,7 +60,9 @@ 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)

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