rspec-signal 0.1.0

data/lib/rspec/signal/parallel_merger.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module RSpec
+  module Signal
+    # Rehydrates worker JSON and performs grouping once, over the complete run.
+    class ParallelMerger
+      Result = Struct.new(:report, :workers, :missing, :write_result, keyword_init: true)
+
+      def initialize(registry:, config: RSpec::Signal.configuration)
+        @registry = registry
+        @config = config
+      end
+
+      def call
+        paths = Dir[File.join(@registry, "*.path")].map { |file| File.read(file).strip }
+        documents, missing = paths.partition { |path| File.file?(path) }
+        payloads = documents.map { |path| JSON.parse(File.read(path)) }
+        validate_configuration!(payloads)
+        apply_configuration(payloads.first&.fetch("configuration", {}) || {})
+        report = aggregate(payloads)
+        result = Result.new(
+          report: report,
+          workers: payloads.size,
+          missing: missing,
+          write_result: Writer.new(@config).write(report)
+        )
+        # Only once we have successfully produced a report: a worker JSON that
+        # failed to parse should stay on disk for a human to look at, not be
+        # deleted along with everything else.
+        cleanup_worker_artifacts(paths)
+        result
+      end
+
+      private
+
+      # Worker payloads are per-run (`workers/<run-id>/<worker-id>/signal.json`),
+      # so once merged into the top-level report they would otherwise sit in
+      # the project forever: a green run's own hygiene guarantee (stale
+      # artifacts never survive a passing suite) does not reach them, and each
+      # payload can carry the full unreduced output of every failure.
+      def cleanup_worker_artifacts(paths)
+        run_directories(paths).each { |directory| FileUtils.rm_rf(directory) }
+      end
+
+      def run_directories(paths)
+        paths.filter_map { |path| File.dirname(path, 2) if path.include?("/workers/") }.uniq
+      end
+
+      def aggregate(payloads)
+        summaries = payloads.map { |payload| payload.fetch("summary", {}) }
+        Report.new(
+          failures: load_failures(payloads),
+          example_count: sum(summaries, "examples"), failure_count: sum(summaries, "failures"),
+          pending_count: sum(summaries, "pending"),
+          duration: summaries.filter_map { |item| item["duration_seconds"] }.max,
+          environment: payloads.first&.fetch("environment", {}) || {},
+          errors_outside_examples: sum(summaries, "errors_outside_examples"), relate_failures: @config.relate_failures
+        )
+      end
+
+      def load_failures(payloads)
+        payloads.flat_map do |payload|
+          payload.fetch("failures", []).map { |failure| load_failure(failure) }
+        end
+      end
+
+      def load_failure(data)
+        entries = data.fetch("trace", []).map { |entry| load_entry(entry) }
+        frames = entries.select(&:frame?)
+        reduced = Backtrace::Reduced.new(entries: entries, total: frames.size + data.fetch("omitted_frames", 0),
+                                         omitted: { serialized: data.fetch("omitted_frames", 0) })
+        fingerprint = data["fingerprint"] || {}
+        Failure.new(**failure_attributes(data, reduced, frames), fingerprint: load_fingerprint(fingerprint))
+      end
+
+      def failure_attributes(data, reduced, frames)
+        { description: data.fetch("description"), spec_location: data.fetch("location"),
+          rerun: data["rerun"], example_id: data["id"], exception_class: data.fetch("exception"),
+          message: load_message(data.fetch("message", [])), reduced: reduced, frames: frames,
+          diagnostics: data.fetch("diagnostics", {}), raw: data["raw"] }
+      end
+
+      def load_fingerprint(data)
+        Fingerprint.new(exception_class: data["exception"], message: "worker", culprit: data["culprit"],
+                        app_context: data["app_context"]).tap do |fingerprint|
+          fingerprint.instance_variable_set(:@digest, data["digest"])
+        end
+      end
+
+      def load_entry(entry)
+        return Backtrace::Gap.new(count: entry.fetch("omitted"), kind: entry.fetch("kind").to_sym) if entry["omitted"]
+
+        location = entry.fetch("location")
+        match = location.match(/\A(.+):(\d+)\z/)
+        path, line = match ? match.captures : [location, nil]
+        Backtrace::Frame.new(raw: location, path: path, display_path: path, line: line&.to_i,
+                             label: entry["label"], kind: entry.fetch("kind").to_sym, gem_name: entry["gem"])
+      end
+
+      def load_message(lines)
+        Message.new(lines, redactor: @config.redactor, project: @config.project, html_threshold: nil)
+      end
+
+      def sum(items, key)
+        number = items.sum { |item| item.fetch(key, 0).to_f }
+        (number % 1).zero? ? number.to_i : number
+      end
+
+      def validate_configuration!(payloads)
+        configurations = payloads.map { |payload| payload.fetch("configuration", {}) }.uniq
+        return if configurations.size <= 1
+
+        raise ArgumentError, "workers reported inconsistent rspec-signal configuration"
+      end
+
+      def apply_configuration(values)
+        values.each { |name, value| @config.public_send("#{name}=", value) if @config.respond_to?("#{name}=") }
+        @config.reset_memoized!
+      end
+    end
+  end
+end

data/lib/rspec/signal/parallel_run.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module RSpec
+  module Signal
+    # Filesystem protocol shared by parallel_tests workers and the parent merger.
+    module ParallelRun
+      RUN_ID = "RSPEC_SIGNAL_RUN_ID"
+      REGISTRY = "RSPEC_SIGNAL_RUN_REGISTRY"
+
+      module_function
+
+      def worker?
+        !ENV[RUN_ID].to_s.empty? && ENV.key?("TEST_ENV_NUMBER")
+      end
+
+      def worker_id
+        value = ENV.fetch("TEST_ENV_NUMBER", "").to_s
+        value.empty? ? "1" : value
+      end
+
+      def write_worker(report, config)
+        directory = File.join(config.output_path, "workers", ENV.fetch(RUN_ID), worker_id)
+        FileUtils.mkdir_p(directory)
+        path = File.join(directory, "signal.json")
+        payload = report.worker_h(write_full: config.write_full)
+                        .merge(worker: worker_id, configuration: configuration_h(config))
+        atomic_write(path, "#{JSON.pretty_generate(payload)}\n")
+        register(path)
+      end
+
+      def configuration_h(config)
+        %i[output_dir project_root max_frames max_external_context max_project_frames fallback_frames
+           max_message_lines max_diff_lines reduce_html max_html_chars max_affected_examples max_groups relate_failures
+           max_clusters max_cluster_specs write_json write_full write_gitignore terminal_summary capture_capybara
+           capture_page_html].to_h { |name| [name, config.public_send(name)] }
+      end
+
+      def register(path)
+        registry = ENV.fetch(REGISTRY)
+        FileUtils.mkdir_p(registry)
+        atomic_write(File.join(registry, "#{worker_id}.path"), "#{path}\n")
+      end
+
+      def atomic_write(path, contents)
+        temporary = "#{path}.#{Process.pid}.tmp"
+        File.write(temporary, contents)
+        File.rename(temporary, path)
+      ensure
+        FileUtils.rm_f(temporary) if defined?(temporary)
+      end
+    end
+  end
+end

data/lib/rspec/signal/project.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    # Knows which paths belong to the project under test ("first party") and how
+    # to render any path compactly.
+    #
+    # First-party means: the host application's own code, plus code from gems
+    # that are developed alongside it (Bundler `path:` sources, local Rails
+    # engines). Those are things the agent can actually open and edit.
+    class Project
+      # Directories that live inside the project root but are not project code.
+      VENDORED = %w[
+        vendor/bundle vendor/cache vendor/ruby .bundle node_modules
+        tmp/ .git/ coverage/
+      ].freeze
+
+      # Matches ".../gems/capybara-3.40.0/lib/capybara/node/finders.rb".
+      #
+      # The leading `.*/` is greedy on purpose: a RubyGems install path contains
+      # "/gems/" twice ("/lib/ruby/gems/3.3.0/gems/capybara-3.40.0/..."), and it
+      # is the last one that introduces the gem.
+      GEM_PATH = %r{
+        \A.*/(?:gems|bundler/gems)/
+        (?<name>[A-Za-z0-9_.-]+?)
+        # A release version, or the short SHA Bundler uses for git sources.
+        (?:-(?<version>\d[\w.]*(?:-[a-z0-9]+)?|[0-9a-f]{12,40}))?
+        /(?<rest>.*)\z
+      }x
+
+      # Matches ".../lib/ruby/3.3.0/json/common.rb" and ".../ruby/3.3.0/x86_64-linux/..."
+      STDLIB_PATH = %r{/lib/ruby/(?:\d+\.\d+\.\d+|site_ruby|vendor_ruby)/(?:[a-z0-9_]+-[a-z0-9_-]+/)?(?<rest>.*)\z}
+
+      attr_reader :root
+
+      # @param root [String] absolute path to the project root
+      # @param extra_first_party [Array<String>] additional absolute path prefixes
+      #   to treat as first party (e.g. a sibling engine checkout)
+      def initialize(root: Dir.pwd, extra_first_party: [])
+        @root = File.expand_path(root)
+        @root_prefix = "#{@root}/"
+        @extra = extra_first_party.map { |p| "#{File.expand_path(p)}/" }
+        @cache = {}
+      end
+
+      # Absolute path prefixes of Bundler `path:` gems (local gems and engines).
+      # Discovered lazily and defensively: any Bundler problem simply means we
+      # fall back to plain root-relative detection.
+      def local_gem_prefixes
+        @local_gem_prefixes ||= discover_local_gem_prefixes
+      end
+
+      def first_party?(path)
+        return false if path.nil? || path.empty?
+
+        @cache[path] ||= compute_first_party(path)
+      end
+
+      # A short, stable, human/agent readable rendering of a path.
+      #
+      #   /app/spec/models/user_spec.rb          -> spec/models/user_spec.rb
+      #   .../gems/capybara-3.40.0/lib/capybara/node/finders.rb -> capybara/node/finders.rb
+      #   .../lib/ruby/3.3.0/json/common.rb      -> ruby/json/common.rb
+      def display_path(path)
+        return path if path.nil? || path.empty?
+
+        absolute = absolutize(path)
+        return relative_to_root(absolute) if under?(absolute, @root_prefix) || first_party?(path)
+
+        if (m = GEM_PATH.match(absolute))
+          return "#{m[:name]}/#{strip_redundant_prefix(m[:name], m[:rest].sub(%r{\Alib/}, ""))}"
+        end
+
+        if (stdlib = STDLIB_PATH.match(absolute))
+          return "ruby/#{stdlib[:rest]}"
+        end
+
+        relative_to_root(absolute)
+      end
+
+      # The gem a path belongs to, or nil.
+      def gem_name(path)
+        m = GEM_PATH.match(absolutize(path))
+        m && m[:name]
+      end
+
+      def absolutize(path)
+        stripped = path.to_s.sub(%r{\A\./}, "")
+        # Ruby emits pseudo-frames that are not file paths at all: "<internal:...>",
+        # "-e", "(eval)", "(irb)". Joining those to the project root would wrongly
+        # make them look first party.
+        return stripped if stripped.start_with?("/", "<", "-", "(")
+
+        File.join(@root, stripped)
+      end
+
+      def relative_to_root(absolute)
+        return absolute[@root_prefix.length..] if under?(absolute, @root_prefix)
+
+        absolute
+      end
+
+      private
+
+      # "activerecord" + "active_record/validations.rb" -> "validations.rb", so the
+      # rendered frame reads `activerecord/validations.rb` rather than repeating
+      # the gem name in two spellings. Only leading *directory* segments that
+      # spell out the gem name are removed.
+      def strip_redundant_prefix(gem_name, rest)
+        segments = rest.split("/")
+        dirs = segments[0..-2] || []
+        target = normalize_gem_name(gem_name)
+
+        dirs.size.downto(1) do |count|
+          return segments[count..].join("/") if normalize_gem_name(dirs[0, count].join) == target
+        end
+
+        rest
+      end
+
+      def normalize_gem_name(name) = name.to_s.delete("-_")
+
+      def compute_first_party(path)
+        absolute = absolutize(path)
+
+        if under?(absolute, @root_prefix)
+          relative = absolute[@root_prefix.length..]
+          return false if VENDORED.any? { |d| relative.start_with?(d) }
+          # A gem unpacked anywhere under the root is still vendored code.
+          return false if GEM_PATH.match?(absolute)
+
+          return true
+        end
+
+        @extra.any? { |p| under?(absolute, p) } ||
+          local_gem_prefixes.any? { |p| under?(absolute, p) }
+      end
+
+      def under?(absolute, prefix)
+        absolute.start_with?(prefix)
+      end
+
+      def discover_local_gem_prefixes
+        return [] unless defined?(::Bundler)
+
+        ::Bundler.load.specs.filter_map do |gem_spec|
+          source = gem_spec.source
+          next unless source.class.name.to_s.include?("Source::Path")
+          next unless gem_spec.full_gem_path
+
+          "#{File.expand_path(gem_spec.full_gem_path)}/"
+        end.uniq
+      rescue StandardError, ::LoadError
+        []
+      end
+    end
+  end
+end

data/lib/rspec/signal/redactor.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    # Best-effort scrubbing of obvious credentials before a report leaves the
+    # machine.
+    #
+    # This is a safety net, not a guarantee. It targets shapes that are
+    # unambiguous (token prefixes, auth headers, credential-ish assignments) and
+    # deliberately does not try to guess at arbitrary secret values, because
+    # false positives destroy the diagnostic value of a report.
+    #
+    # Always review artifacts before sending them somewhere you do not control.
+    class Redactor
+      PLACEHOLDER = "[REDACTED]"
+
+      # Keys whose *values* are considered sensitive.
+      SENSITIVE_KEY = /
+        (?:api[_-]?key|secret[_-]?key|access[_-]?key|client[_-]?secret|private[_-]?key|
+           secret|password|passwd|pwd|token|auth[_-]?token|access[_-]?token|refresh[_-]?token|
+           session[_-]?id|csrf|cookie|authorization|credentials?)
+      /xi
+
+      DEFAULT_PATTERNS = [
+        # Authorization: Bearer xyz / Basic xyz
+        /\b(Authorization\s*[:=]\s*["']?\s*(?:Bearer|Basic|Token)\s+)[^\s"',;)\]}]+/i,
+        # key: "value" / key => 'value' / key=value / "key":"value"
+        /(["']?#{SENSITIVE_KEY.source}["']?\s*(?:=>|[:=])\s*)(["'])(?:(?!\2).){3,}\2/xi,
+        /(\b#{SENSITIVE_KEY.source}\s*=\s*)(?!["'])[^\s"',;&)\]}]{3,}/xi,
+        # URL query parameters
+        /([?&]#{SENSITIVE_KEY.source}=)[^&\s"'<>]+/xi,
+        # URL userinfo: https://user:pass@host
+        %r{(\b[a-z][a-z0-9+.-]*://[^/\s:@]+:)[^/\s@]+(@)}i,
+        # Well-known token shapes
+        /\bAKIA[0-9A-Z]{16}\b/,
+        /\bASIA[0-9A-Z]{16}\b/,
+        /\bgh[pousr]_[A-Za-z0-9]{20,}\b/,
+        /\bgithub_pat_[A-Za-z0-9_]{20,}\b/,
+        /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
+        /\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,}\b/,
+        /\bglpat-[A-Za-z0-9_-]{16,}\b/,
+        /\bAIza[0-9A-Za-z_-]{30,}\b/,
+        # JWTs
+        /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*/,
+        # PEM blocks
+        /-----BEGIN[A-Z ]*PRIVATE KEY-----.*?-----END[A-Z ]*PRIVATE KEY-----/m
+      ].freeze
+
+      def initialize(enabled: true, patterns: DEFAULT_PATTERNS, extra_patterns: [], filter: nil)
+        @enabled = enabled
+        @patterns = patterns + Array(extra_patterns)
+        @filter = filter
+      end
+
+      def enabled? = @enabled
+
+      # @param text [String, nil]
+      # @return [String, nil]
+      def call(text)
+        return text if text.nil? || !@enabled
+
+        result = text.dup
+        @patterns.each do |pattern|
+          result = result.gsub(pattern) do |match|
+            replacement_for(pattern, match, Regexp.last_match)
+          end
+        end
+        result = @filter.call(result) if @filter
+        result
+      end
+      alias scrub call
+
+      private
+
+      # Patterns with capture groups keep the identifying prefix so the report
+      # still says *what* was redacted.
+      def replacement_for(_pattern, match, captures)
+        prefix = captures[1]
+        return PLACEHOLDER if prefix.nil?
+
+        suffix = captures[2] if captures[2] && captures[2] == "@"
+        quote = captures[2] if captures[2] && %w[" '].include?(captures[2])
+
+        return "#{prefix}#{quote}#{PLACEHOLDER}#{quote}" if quote
+        return "#{prefix}#{PLACEHOLDER}#{suffix}" if suffix
+
+        "#{prefix}#{PLACEHOLDER}" if match
+      end
+    end
+  end
+end

data/lib/rspec/signal/report.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    # The complete, renderer-independent result of a run.
+    class Report
+      attr_reader :failures, :groups, :clusters, :example_count, :failure_count, :pending_count,
+                  :duration, :seed, :seed_used, :environment, :errors_outside_examples
+
+      def initialize(failures:, example_count: 0, failure_count: nil, pending_count: 0,
+                     duration: nil, seed: nil, seed_used: false, environment: {},
+                     errors_outside_examples: 0, relate_failures: true)
+        @failures = failures
+        @groups = Grouper.call(failures)
+        @clusters = relate_failures ? safely { Clusterer.call(failures) } : []
+        @example_count = example_count
+        @failure_count = failure_count || failures.size
+        @pending_count = pending_count
+        @duration = duration
+        @seed = seed
+        @seed_used = seed_used
+        @environment = environment
+        @errors_outside_examples = errors_outside_examples
+      end
+
+      # Clustering is the newest and least essential stage; a report without it
+      # is still worth having, so it is never allowed to take the run down.
+      def safely
+        yield
+      rescue StandardError
+        []
+      end
+
+      def group_count   = groups.size
+      def cluster_count = clusters.size
+      def any_failures? = !failures.empty?
+      def seed_used? = !!@seed_used
+
+      # Backtrace frames dropped across the whole run. This is the number that
+      # makes the reduction visible.
+      def omitted_frames
+        @omitted_frames ||= failures.sum { |failure| failure.reduced.omitted_count }
+      end
+
+      def total_frames
+        @total_frames ||= failures.sum { |failure| failure.reduced.total }
+      end
+
+      def kept_frames = total_frames - omitted_frames
+
+      def to_h
+        {
+          schema: 1,
+          generated_by: "rspec-signal #{VERSION}",
+          summary: {
+            examples: example_count,
+            failures: failure_count,
+            pending: pending_count,
+            signatures: group_count,
+            related_clusters: cluster_count.positive? ? cluster_count : nil,
+            duration_seconds: duration&.round(3),
+            seed: seed_used? ? seed : nil,
+            errors_outside_examples: errors_outside_examples.positive? ? errors_outside_examples : nil
+          }.compact,
+          environment: environment,
+          backtrace_reduction: { total_frames: total_frames, kept_frames: kept_frames, omitted_frames: omitted_frames },
+          signatures: groups.map(&:to_h),
+          related: clusters.map(&:to_h)
+        }
+      end
+
+      # Worker interchange data. Unlike the public report summary this retains
+      # every reduced failure so grouping can be repeated across all workers.
+      #
+      # `raw` -- the unreduced formatter output -- is included only when
+      # `write_full` is on, since it is otherwise discarded on merge and would
+      # just bloat every worker payload for no reason.
+      def worker_h(write_full: false)
+        serialized = failures.map do |failure|
+          attributes = failure.to_h.merge(fingerprint: failure.fingerprint.to_h)
+          attributes[:raw] = failure.raw if write_full
+          attributes
+        end
+        to_h.merge(schema: 2, failures: serialized)
+      end
+    end
+  end
+end

data/lib/rspec/signal/reporters/full_output.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Reporters
+      # The unreduced failure output, preserved verbatim.
+      #
+      # This exists so reduction is never lossy in practice: if the compact
+      # report dropped the one frame that mattered, the original is one file
+      # away. It is not the artifact you hand to an agent.
+      class FullOutput
+        def initialize(report, config)
+          @report = report
+          @config = config
+        end
+
+        def render
+          out = ["rspec-signal #{VERSION} -- unreduced failure output", ""]
+          @report.failures.each_with_index do |failure, index|
+            out << (failure.raw || fallback(failure, index + 1))
+            out << ""
+          end
+          "#{out.join("\n").rstrip}\n"
+        end
+
+        private
+
+        def fallback(failure, position)
+          lines = ["  #{position}) #{failure.description}",
+                   "     #{failure.exception_class}:",
+                   *failure.message.lines.map { |line| "       #{line}" }]
+          lines.concat(failure.frames.map { |frame| "     # #{frame}" })
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/rspec/signal/reporters/json_report.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RSpec
+  module Signal
+    module Reporters
+      # Machine-readable twin of the Markdown report, for tooling and CI.
+      class JsonReport
+        def initialize(report, _config = nil)
+          @report = report
+        end
+
+        def render
+          "#{JSON.pretty_generate(@report.to_h)}\n"
+        end
+      end
+    end
+  end
+end