rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/time_formatter.rb

@@ -1,10 +1,21 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # Internal TimeFormatter — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  #
+  # Internal helper for human-friendly elapsed-time formatting in
+  # tracer log lines and the terminal reporter (e.g. "1 minute 23 seconds").
   module TimeFormatter
+    # Internal constant.
+    # @api private
     DEFAULT_PRECISION = 2
+    # Internal constant.
+    # @api private
     SECONDS_PRECISION = 5
 
+    # Internal constant.
+    # @api private
     UNITS = {
       second: 60,
       minute: 60,
@@ -12,9 +23,9 @@ module RSpecTracer
       day: Float::INFINITY
     }.freeze
 
-    module_function
-
-    def format_time(seconds)
+    # Internal helper for the tracer pipeline.
+    # @api private
+    def self.format_time(seconds)
       return pluralize(format_duration(seconds), 'second') if seconds < 60
 
       formatted_duration = UNITS.each_pair.with_object([]) do |(unit, count), duration|
@@ -30,26 +41,34 @@ module RSpecTracer
       formatted_duration.reverse.join(' ')
     end
 
-    def format_duration(duration)
-      return 0 if duration.negative?
+    class << self
+      private
 
-      precision = duration < 1 ? SECONDS_PRECISION : DEFAULT_PRECISION
+      # Internal method on the tracer pipeline.
+      # @api private
+      def format_duration(duration)
+        return 0 if duration.negative?
 
-      strip_trailing_zeroes(format("%<duration>0.#{precision}f", duration: duration))
-    end
+        precision = duration < 1 ? SECONDS_PRECISION : DEFAULT_PRECISION
 
-    def strip_trailing_zeroes(formatted_duration)
-      formatted_duration.sub(/(?:(\..*[^0])0+|\.0+)$/, '\1')
-    end
+        strip_trailing_zeroes(format("%<duration>0.#{precision}f", duration: duration))
+      end
 
-    def pluralize(duration, unit)
-      if (duration.to_f - 1).abs < Float::EPSILON
-        "#{duration} #{unit}"
-      else
-        "#{duration} #{unit}s"
+      # Internal method on the tracer pipeline.
+      # @api private
+      def strip_trailing_zeroes(formatted_duration)
+        formatted_duration.sub(/(?:(\..*[^0])0+|\.0+)$/, '\1')
       end
-    end
 
-    private_class_method :format_duration, :strip_trailing_zeroes, :pluralize
+      # Internal method on the tracer pipeline.
+      # @api private
+      def pluralize(duration, unit)
+        if (duration.to_f - 1).abs < Float::EPSILON
+          "#{duration} #{unit}"
+        else
+          "#{duration} #{unit}s"
+        end
+      end
+    end
   end
 end

data/lib/rspec_tracer/tracker/README.md

@@ -0,0 +1,36 @@
+# Tracker
+
+Core engine for input identification. A test is a pure function of its
+inputs; this layer identifies every input and hashes it.
+
+## Responsibilities
+
+- Observe Ruby-executed source via `Coverage`.
+- Intercept file I/O (`File`, `IO`, `YAML`, `JSON`, `Kernel`).
+- Subscribe to framework notifications (`ActiveSupport::Notifications`).
+- Evaluate user-declared globs.
+- Track whole-suite invalidators (`Gemfile.lock`, `.ruby-version`, config,
+  gem version).
+- Build the dependency graph and expose `affected_examples` to the
+  filter.
+
+## Public protocol
+
+```ruby
+module RSpecTracer::Tracker
+  def setup(configuration:); end
+  def start_example(example_id); end
+  def stop_example(example_id); end
+  def affected_examples(all_example_ids); end
+  def finalize; end
+end
+```
+
+Each input type has exactly one observation mechanism. Declared globs
+take precedence over auto-interception for overlapping files.
+
+## Status
+
+Placeholder for 2.0. Legacy 1.x tracking logic lives in
+`lib/rspec_tracer/` top-level files (`runner.rb`, `rspec_reporter.rb`,
+`ruby_coverage.rb`, `cache.rb`) and migrates here during Phase 3.

data/lib/rspec_tracer/tracker/coverage_adapter.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'coverage'
+require 'set'
+
+require_relative 'file_digest'
+require_relative 'input'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Wraps Ruby's built-in ::Coverage module. The first observer in
+    # the 2.0 tracker pipeline -- ingests the per-file line-coverage
+    # bitmap that MRI/JRuby maintain natively, normalizes the two
+    # possible shapes (array vs SimpleCov-style hash) and emits
+    # Tracker::Input values for the files touched between two peeks.
+    #
+    # All state lives on the instance; no reads from RSpecTracer.*.
+    # Pass root, filters, and mode at construction time.
+    #
+    # Content digest is SHA256 hex (see Input's file-level comment).
+    # Changing the algorithm is a storage schema_version bump.
+    class CoverageAdapter
+      # ::Coverage.peek_result returns one of two shapes:
+      #   :array -- { path => [hit_counts | nil, ...] }           (default)
+      #   :hash  -- { path => { lines: [...], branches: {...} } } (SimpleCov
+      #                                                           with branch
+      #                                                           coverage)
+      # :auto detects on the first peek by sniffing a value's type.
+      MODES = %i[auto array hash].freeze
+
+      # Internal attribute.
+      # @api private
+      attr_reader :root, :filters, :mode
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize(root:, filters: [], mode: :auto)
+        raise ArgumentError, "invalid mode: #{mode.inspect}, allowed: #{MODES}" \
+          unless MODES.include?(mode)
+
+        @root = File.expand_path(root)
+        @root_prefix = "#{@root}/"
+        @filters = filters
+        @mode = mode
+      end
+
+      # Snapshot of the current coverage state: { absolute_path =>
+      # Array<Integer|nil> } for files under project root that survive
+      # the user filter. Hash-mode input is reduced to its :lines
+      # component -- 2.0 ignores branch coverage (same as 1.x; noted in
+      # the upgrade docs).
+      def peek
+        peek_normalized { |path| filtered?(path) }
+      end
+
+      # Same shape as #peek but only filters by `@root_prefix` -- skips
+      # the user `filters` filter. The coverage.json emitter
+      # (`Reporters::CoverageJsonReporter`) calls this at finalize to
+      # capture cumulative coverage matching legacy semantics: 1.x's
+      # CoverageReporter#peek_coverage applied no `filters` filter at
+      # peek time and let `coverage_filters` do the final exclusion.
+      # Routing the emitter's finalize peek through this method keeps
+      # the lib/-wide `::Coverage.peek_result` call-site count at 3
+      # (one per file: this adapter, rspec/installation, and
+      # tracker/loaded_files_tracker) instead of adding a fourth.
+      def peek_unfiltered
+        peek_normalized { false }
+      end
+
+      # Same root-prefix scoping as #peek_unfiltered, but preserves
+      # Coverage's full per-file shape (Hash `{ lines: [...], branches:
+      # {...} }` in hash mode; Array<Integer|nil> in array mode) instead
+      # of reducing hash entries to their `:lines` component.
+      #
+      # Lone caller is the SimpleCov interop shim
+      # (`Reporters::CoverageJsonReporter::SimpleCovInterop`): when
+      # SimpleCov has `enable_coverage :branch`, Coverage runs in hash
+      # mode and the prepended `Coverage.result` MUST hand back the
+      # branches sub-hash so SimpleCov's branch-coverage report path
+      # has data to render. The legacy `peek_unfiltered` strips
+      # branches because the user-facing `coverage.json` shape is
+      # documented as `Array<Integer|nil>` per file (1.x compatibility);
+      # do not change `peek_unfiltered` to do otherwise without bumping
+      # the storage schema.
+      def peek_unfiltered_full
+        raw = ::Coverage.peek_result
+        @mode = detect_mode(raw) if @mode == :auto
+
+        raw.each_with_object({}) do |(path, stats), acc|
+          next unless path.start_with?(@root_prefix)
+
+          acc[path] = stats
+        end
+      end
+
+      # Pure function: returns Set<Input> for files whose line arrays
+      # changed between `before` and `after`. Handles nil line entries
+      # (unexecutable lines) correctly -- nil<->nil is not a delta, any
+      # other transition is.
+      def compute_diff(before, after)
+        changed = Set.new
+        (before.keys | after.keys).each do |path|
+          next unless delta?(before[path], after[path])
+
+          changed << Input.for_file(
+            path: path,
+            kind: :ruby,
+            digest: file_digest(path),
+            root: @root
+          )
+        end
+        changed
+      end
+
+      private
+
+      # Single owner of the `::Coverage.peek_result` call site for
+      # `peek` and `peek_unfiltered`. Skip block decides exclusion;
+      # everything that survives gets normalized through the array/hash
+      # mode handling.
+      def peek_normalized
+        raw = ::Coverage.peek_result
+        @mode = detect_mode(raw) if @mode == :auto
+
+        raw.each_with_object({}) do |(path, stats), acc|
+          next unless path.start_with?(@root_prefix)
+          next if yield(path)
+
+          acc[path] = @mode == :hash ? stats[:lines] : stats
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def detect_mode(raw)
+        return :array if raw.empty?
+
+        raw.each_value.first.is_a?(Hash) ? :hash : :array
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def filtered?(path)
+        return false if @filters.empty?
+
+        # Legacy filter convention: file_name is root-stripped with
+        # leading slash. Keep it so existing .rspec-tracer filter
+        # strings/regexes work under the new adapter unchanged.
+        file_name = path.sub(@root, '')
+        @filters.any? { |f| f.match?(file_name: file_name) }
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def delta?(before, after)
+        return true if before.nil? || after.nil?
+        return true if before.length != after.length
+
+        before.each_with_index do |bv, i|
+          return true unless bv == after[i]
+        end
+        false
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def file_digest(path)
+        FileDigest.compute(path)
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/declared_globs.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require_relative 'file_digest'
+require_relative 'input'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Observer #3 in the 2.0 tracker pipeline (CoverageAdapter = #1,
+    # IOHooks = #2). Walks user-declared glob patterns at boot, digests
+    # each matching file, and emits :declared Inputs. Declared globs
+    # cover inputs that cannot be auto-observed - files no app code
+    # reads (Gemfile.lock, .rspec-tracer), or files that might not be
+    # rendered during a given run (a newly-added template).
+    #
+    # Exposes #covers? so IOHooks can skip paths the declared-globs
+    # walk already observed. ARCHITECTURE rule (Input taxonomy): "if
+    # the user declares a glob that covers the same files we auto-
+    # intercept, the declared glob takes precedence."
+    #
+    # Graceful degradation (CLAUDE.md): an unreadable declared file is
+    # skipped silently - the tracer never propagates failure into the
+    # user's test suite. Identity-based Set dedup collapses overlap
+    # when two globs match the same file.
+    class DeclaredGlobs
+      # FNM_PATHNAME keeps `*` from eating `/` so globs walk directory
+      # boundaries predictably. FNM_EXTGLOB enables `{a,b}` alternation
+      # so `coverage_track_files '{app,lib}/**/*.rb'` (a real pattern
+      # in the sample projects) matches the same files `Dir.glob` would.
+      FNMATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+      # Internal attribute.
+      # @api private
+      attr_reader :root, :globs
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize(root:, globs: [])
+        @root = File.expand_path(root)
+        @root_prefix = "#{@root}/"
+        @globs = Array(globs).flatten.compact.map(&:to_s).uniq.freeze
+      end
+
+      # Memoized across calls - the architecture constraint is "glob
+      # walk at boot is a single pass; result cached for the life of
+      # the tracker instance."
+      def walk
+        @walk ||= compute_walk
+      end
+
+      # O(N_globs) per call; N is typically 1-10. Absolute paths only -
+      # the callers (IOHooks precedence, NewFileDetector diff) always
+      # hold absolute paths. Paths outside root never match.
+      def covers?(path)
+        return false if @globs.empty?
+        return false unless path.start_with?(@root_prefix)
+
+        rel = path[@root_prefix.length..]
+        @globs.any? { |glob| File.fnmatch?(glob, rel, FNMATCH_FLAGS) }
+      end
+
+      # Per-example attribution. Declared inputs attach to every
+      # example in the suite (per-example narrowing is available via
+      # the per-example `tracks:` DSL). Each example gets its own Set
+      # copy so downstream mutation of one example's input set does
+      # not leak into siblings.
+      def attribute_to(example_ids)
+        inputs = walk
+        example_ids.to_h { |id| [id, Set.new(inputs)] }
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def compute_walk
+        @globs.each_with_object(Set.new) do |glob, acc|
+          Dir.glob(glob, base: @root).each do |rel|
+            abs = File.expand_path(rel, @root)
+            next unless abs.start_with?(@root_prefix) && File.file?(abs)
+
+            digest = file_digest(abs)
+            next if digest.nil?
+
+            acc << Input.for_file(path: abs, kind: :declared, digest: digest, root: @root)
+          end
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def file_digest(path)
+        FileDigest.compute(path)
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/dependency_graph.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Directed bipartite graph over (example_id, file path). The
+    # forward map answers "which files does this example depend on?";
+    # the memoized inverse answers "which examples depend on this
+    # file?" in O(1) per lookup.
+    #
+    # The graph is append-only during a run. `register_example` is
+    # called once per example at example-finished time with the Input
+    # set that CoverageAdapter + IOHooks + DeclaredGlobs collected.
+    # The inverse is invalidated on every register_example and lazily
+    # rebuilt on the next `examples_depending_on` call.
+    #
+    # Keyed by file path, not Input identity
+    # -------------------------------------
+    # An earlier design framed the inverse as "input_identity -> Set<example_id>",
+    # which embeds the Input#kind (e.g. "ruby:lib/foo.rb" vs
+    # "declared:lib/foo.rb"). In practice the change-set that drives
+    # filtering comes from diffing Snapshot.all_files digests, which
+    # is keyed by path only - the kind that observed the file is not
+    # recoverable from a digest mismatch. Keying the graph by path
+    # eliminates that recovery burden and matches 1.x's
+    # dependency.json shape exactly (Hash[example_id => Set<path>]),
+    # keeping the Snapshot byte-compatible. Kind-aware filtering, if
+    # ever needed, can layer on top without changing the graph shape.
+    #
+    # API accepts Set<Input>, Set<String>, or any mix - anything that
+    # responds to :path is treated as an Input; otherwise `.to_s`.
+    # This keeps observer call sites terse (pass the Input set
+    # directly) without forcing Snapshot-load sites to reconstruct
+    # Input objects from paths.
+    class DependencyGraph
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize
+        @forward = {}
+        @inverse_index = nil
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def register_example(example_id, inputs)
+        @forward[example_id] = coerce_paths(inputs)
+        @inverse_index = nil
+        self
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def paths_for(example_id)
+        @forward[example_id] || Set.new
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def example_ids
+        @forward.keys
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def empty?
+        @forward.empty?
+      end
+
+      # O(|change_set| x avg-examples-per-file). `change_set` can be
+      # a Set<Input>, Set<String>, or any mix - coerced the same way
+      # `register_example` coerces its inputs arg.
+      def examples_depending_on(change_set)
+        return Set.new if @forward.empty?
+
+        paths = coerce_paths(change_set)
+        return Set.new if paths.empty?
+
+        affected = Set.new
+        paths.each do |path|
+          ids = inverse_index[path]
+          affected.merge(ids) if ids
+        end
+        affected
+      end
+
+      # Snapshot projection. `dependency_hash` feeds
+      # Snapshot.dependency; `reverse_dependency_hash` feeds
+      # Snapshot.reverse_dependency. Both return fresh Sets per value
+      # so downstream mutation can't leak into the graph's state.
+      def dependency_hash
+        @forward.transform_values(&:dup)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def reverse_dependency_hash
+        inverse_index.transform_values(&:dup)
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def coerce_paths(collection)
+        return Set.new if collection.nil?
+
+        collection.each_with_object(Set.new) do |entry, acc|
+          acc << (entry.respond_to?(:path) ? entry.path : entry.to_s)
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def inverse_index
+        @inverse_index ||= build_inverse_index
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def build_inverse_index
+        map = {}
+        @forward.each do |example_id, paths|
+          paths.each do |path|
+            (map[path] ||= Set.new) << example_id
+          end
+        end
+        map
+      end
+    end
+  end
+end

data/lib/rspec_tracer/tracker/env_matcher.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal Tracker — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Tracker
+    # Wildcard env matching helper.
+    #
+    # Lives outside Configuration so configure's alias loop does not
+    # leak its private helpers as public _name DSL surface
+    # (memory: feedback_configure_dsl_private_leak). Pure utility
+    # module; def self.x style for mutant observability
+    # (memory: feedback_mutation_friendly_modules). ASCII-only source
+    # (memory: feedback_mutant_non_ascii_source).
+    #
+    # Patterns accepted:
+    #   - Literal env name              "AUTH_TOKEN"
+    #   - Single trailing wildcard      "RAILS_*"
+    #   - Single leading wildcard       "*_TOKEN"
+    #   - Bare wildcard (matches all)   "*"
+    #
+    # Patterns rejected (raise ArgumentError):
+    #   - Multi-segment / embedded *    "RAILS_*_ENV"
+    #   - Multiple *                    "RAILS_*_*"
+    #   - Character classes             "RAILS_[A-Z]*"
+    #   - Negation / glob escape        "RAILS_!ENV", "RAILS_\X"
+    #   - Question mark                 "RAILS_?ENV"
+    #   - Empty / nil
+    module EnvMatcher
+      # Internal constant.
+      # @api private
+      WILDCARD = '*'
+      # Internal constant.
+      # @api private
+      DISALLOWED_CHARS = %w[? [ ] ! \\].freeze
+
+      # Boolean: does the pattern contain at least one wildcard?
+      def self.wildcard?(pattern)
+        pattern.to_s.include?(WILDCARD)
+      end
+
+      # Expand a list of patterns against env keys. Literals pass
+      # through; wildcards are anchored + grepped against env.keys.
+      # Returns a deduped Array<String> in input order.
+      #
+      # `env` is injectable for testability; defaults to ::ENV. Reads
+      # only env.keys, never values.
+      def self.expand(patterns, env: ::ENV)
+        result = []
+        patterns.each do |pattern|
+          str = pattern.to_s
+          validate!(str)
+          if wildcard?(str)
+            re = glob_to_regex(str)
+            env.each_key { |k| result << k if re.match?(k) }
+          else
+            result << str
+          end
+        end
+        result.uniq
+      end
+
+      # Boolean: does `name` match `pattern`? Single-pattern variant
+      # of expand for ad-hoc checks (specs, future call sites). Named
+      # `match_glob?` (predicate suffix) per Naming/PredicateMethod.
+      def self.match_glob?(pattern, name)
+        str = pattern.to_s
+        validate!(str)
+        return str == name.to_s unless wildcard?(str)
+
+        glob_to_regex(str).match?(name.to_s)
+      end
+
+      # Raise ArgumentError on unsupported pattern syntax. Called
+      # before any regex build so users see a clear message at
+      # config-load time (Engine#setup) or at RunnerHook Pass 1
+      # (per-example metadata) rather than a regex parse crash.
+      # rubocop:disable Metrics/PerceivedComplexity
+      def self.validate!(pattern)
+        if pattern.nil? || pattern.empty?
+          raise ArgumentError,
+                "track_env pattern must be a non-empty String (got #{pattern.inspect})"
+        end
+
+        DISALLOWED_CHARS.each do |c|
+          next unless pattern.include?(c)
+
+          raise ArgumentError,
+                "track_env pattern #{pattern.inspect} contains unsupported character " \
+                "#{c.inspect} (allowed: literals, single trailing/leading *)"
+        end
+
+        return if pattern == WILDCARD
+
+        stars = pattern.count(WILDCARD)
+        return if stars.zero?
+
+        if stars > 1
+          raise ArgumentError,
+                "track_env pattern #{pattern.inspect} contains multiple wildcards " \
+                '(only one * is allowed, at the start or end)'
+        end
+
+        return if pattern.start_with?(WILDCARD) || pattern.end_with?(WILDCARD)
+
+        raise ArgumentError,
+              "track_env pattern #{pattern.inspect} has an embedded wildcard " \
+              '(only single trailing/leading * is supported, e.g. PREFIX_* or *_SUFFIX)'
+      end
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Build an anchored regex from a wildcard pattern. `*` becomes
+      # `[^=]*` (env names contain no `=` by Posix; defensive). Anchors
+      # are mandatory or "RAILS_*" would match "MY_RAILS_THING".
+      # Private singleton helper - exposed only via match_glob / expand.
+      class << self
+        private
+
+        # Internal method on the tracer pipeline.
+        # @api private
+        def glob_to_regex(pattern)
+          /\A#{Regexp.escape(pattern).gsub('\\*', '[^=]*')}\z/
+        end
+      end
+    end
+  end
+end