rspec-signal 0.1.0

data/lib/rspec/signal/symptoms/ruby_error.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Symptoms
+      # Two Ruby-level messages specific enough to cluster on: a method called
+      # on the wrong thing, and a constant that was never defined.
+      #
+      # `undefined method 'progress' for nil` in six specs is one nil, not six
+      # bugs. Both the method and the receiver are part of the key, so
+      # `#name for nil` and `#total for nil` stay apart.
+      module RubyError
+        # Ruby 3.4 quotes with `'x'`, earlier versions with `` `x' ``.
+        UNDEFINED_METHOD = /undefined method [`'"](?<name>[^'"`]+)['"`] for (?:an instance of )?(?<receiver>\S+)/
+        UNINITIALIZED    = /uninitialized constant (?<constant>[A-Z]\w*(?:::\w+)*)/
+
+        module_function
+
+        def call(_failure, text)
+          undefined_method(text) || uninitialized_constant(text)
+        end
+
+        def undefined_method(text)
+          match = UNDEFINED_METHOD.match(text)
+          return nil unless match
+
+          name = match[:name]
+          receiver = receiver_name(match[:receiver])
+          Symptom.new(kind: :undefined_method, key: "undefined-method:#{name}:#{receiver}",
+                      label: "undefined method `#{name}` on #{receiver}",
+                      detail: "undefined `#{name}` for #{receiver}")
+        end
+
+        def uninitialized_constant(text)
+          match = UNINITIALIZED.match(text)
+          return nil unless match
+
+          constant = match[:constant]
+          Symptom.new(kind: :missing_constant, key: "missing-constant:#{constant}",
+                      label: "uninitialized constant `#{constant}`", detail: "uninitialized #{constant}")
+        end
+
+        # `nil:NilClass`, `#<User:0x00007f9a>` and `an instance of User` all
+        # name a class; use it, so two receivers of the same class cluster.
+        def receiver_name(raw)
+          text = raw.to_s
+          return "nil" if text.start_with?("nil")
+          return ::Regexp.last_match(1) if text =~ /\A#<([A-Z]\w*(?:::\w+)*)/
+
+          text.split(":").first.to_s
+        end
+      end
+    end
+  end
+end

data/lib/rspec/signal/symptoms/selector.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Symptoms
+      # A DOM node or piece of page text Capybara could not find.
+      #
+      # The same selector missing from four pages is one missing partial, one
+      # renamed `data-testid`, one component that never mounted. Capybara says
+      # so two different ways depending on whether you used `find` or
+      # `have_css`, and those two produce different exception classes and
+      # different messages, so they are correctly different signatures -- but
+      # they are obviously the same symptom.
+      #
+      # The selector itself is the cluster key, compared exactly. Two different
+      # selectors never meet.
+      module Selector
+        TYPES = "css|xpath|field|link or button|link|button|select box|checkbox|" \
+                "radio button|file field|fillable field|element|selector|table"
+        # The selector as Capybara printed it: inspected, or a bare token.
+        TARGET = /"(?:[^"\\]|\\.)*"|\S+/
+        VISIBILITY = "(?:visible |invisible )?"
+
+        # `find(...)` and friends raise Capybara::ElementNotFound.
+        UNABLE = /Unable to find #{VISIBILITY}(?<type>#{TYPES})\s+(?<target>#{TARGET})/i
+        # `expect(page).to have_css(...)` fails the matcher instead, with a
+        # different class and a different sentence for the same missing node.
+        NO_MATCHES = Regexp.new("expected to find #{VISIBILITY}(?<type>#{TYPES})\\s+(?<target>#{TARGET})" \
+                                ".{0,200}?but there were no matches", Regexp::IGNORECASE)
+        # Page text is not a selector, but it goes missing for the same reasons.
+        TEXT = /(?:Unable to find|expected to find) text (?<target>#{TARGET})/i
+
+        module_function
+
+        def call(_failure, text)
+          match = NO_MATCHES.match(text) || UNABLE.match(text)
+          return missing_text(text) unless match
+
+          target = unquote(match[:target])
+          return nil if target.empty?
+
+          type = match[:type].to_s.downcase
+          Symptom.new(kind: :selector, key: "selector:#{type}:#{target}",
+                      label: "missing #{type} selector `#{safe(target)}`",
+                      detail: "no match for #{type} #{target}")
+        end
+
+        def missing_text(text)
+          match = TEXT.match(text)
+          return nil unless match
+
+          target = unquote(match[:target])
+          return nil if target.empty?
+
+          Symptom.new(kind: :missing_text, key: "text:#{target}",
+                      label: "missing page text `#{safe(target)}`",
+                      detail: "page did not contain \"#{target}\"")
+        end
+
+        # Capybara prints the selector with `inspect`, so a `[data-testid="x"]`
+        # arrives with its inner quotes escaped.
+        def unquote(raw)
+          text = raw.to_s
+          text = text[1..-2].to_s.gsub('\\"', '"').gsub("\\\\", "\\") if text.start_with?('"')
+          text.gsub(/\s+/, " ").strip
+        end
+
+        def safe(target) = target.tr("`", "'")
+      end
+    end
+  end
+end

data/lib/rspec/signal/symptoms.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "symptoms/http_status"
+require_relative "symptoms/route"
+require_relative "symptoms/selector"
+require_relative "symptoms/record"
+require_relative "symptoms/ruby_error"
+require_relative "symptoms/exception_class"
+
+module RSpec
+  module Signal
+    # The symptom extractors, in the order they are tried.
+    #
+    # A failure takes the first symptom that matches and no more, so it belongs
+    # to at most one related cluster. The order is significance, not
+    # convenience: a 404 in a request spec is a better organising fact than the
+    # exception class that carried it, and the exception class is a worse one
+    # than everything above it, which is why it is last.
+    module Symptoms
+      EXTRACTORS = [HttpStatus, Route, Selector, Record, RubyError, ExceptionClass].freeze
+
+      module_function
+
+      # @param failure [Failure]
+      # @return [Symptom, nil]
+      def for(failure)
+        text = one_line(failure.message.text)
+        EXTRACTORS.each do |extractor|
+          symptom = extractor.call(failure, text)
+          return symptom if symptom
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Extractor patterns are written against a single line: RSpec wraps the
+      # same sentence differently depending on matcher and terminal width.
+      def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+    end
+  end
+end

data/lib/rspec/signal/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    VERSION = "0.1.0"
+  end
+end

data/lib/rspec/signal/writer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RSpec
+  module Signal
+    # Puts artifacts on disk.
+    #
+    # A run with no failures removes artifacts from previous runs, so an agent
+    # can never be handed a stale report that describes failures you already
+    # fixed.
+    class Writer
+      SIGNAL   = "signal.md"
+      JSON     = "signal.json"
+      FULL     = "full.txt"
+      MANAGED  = [SIGNAL, JSON, FULL].freeze
+
+      Result = Struct.new(:summary_path, :written, :cleaned, keyword_init: true)
+
+      def initialize(config)
+        @config = config
+      end
+
+      def dir = @config.output_path
+
+      def write(report)
+        return clean if report.failures.empty? && report.errors_outside_examples.zero?
+
+        FileUtils.mkdir_p(dir)
+        write_gitignore
+
+        markdown = Reporters::Markdown.new(report, @config).render
+        written = [write_file(SIGNAL, markdown)]
+        written.concat(optional_artifacts(report))
+
+        stale = MANAGED - written.map { |path| File.basename(path) }
+        Result.new(summary_path: File.join(dir, SIGNAL), written: written, cleaned: remove(stale))
+      end
+
+      # Relative to the project root when possible, because that is what you
+      # type and what an agent resolves.
+      def relative(path)
+        root = "#{@config.root}/"
+        path.start_with?(root) ? path[root.length..] : path
+      end
+
+      private
+
+      def optional_artifacts(report)
+        written = []
+        written << write_file(JSON, Reporters::JsonReport.new(report, @config).render) if @config.write_json
+        written << write_file(FULL, Reporters::FullOutput.new(report, @config).render) if @config.write_full
+        written
+      end
+
+      def clean
+        Result.new(summary_path: nil, written: [], cleaned: remove(MANAGED))
+      end
+
+      def remove(names)
+        names.filter_map do |name|
+          path = File.join(dir, name)
+          next unless File.file?(path)
+
+          File.delete(path)
+          path
+        end
+      end
+
+      def write_file(name, contents)
+        path = File.join(dir, name)
+        File.write(path, contents)
+        path
+      end
+
+      # Failure artifacts routinely contain application data. Keeping them out of
+      # version control by default is cheap insurance.
+      def write_gitignore
+        return unless @config.write_gitignore
+
+        path = File.join(dir, ".gitignore")
+        return if File.exist?(path)
+
+        File.write(path, "# Written by rspec-signal. Artifacts can contain application data.\n*\n")
+      end
+    end
+  end
+end

data/lib/rspec/signal.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+
+require_relative "signal/version"
+require_relative "signal/project"
+require_relative "signal/backtrace/frame"
+require_relative "signal/backtrace/parser"
+require_relative "signal/backtrace/classifier"
+require_relative "signal/backtrace/reducer"
+require_relative "signal/redactor"
+require_relative "signal/html_summary"
+require_relative "signal/message"
+require_relative "signal/fingerprint"
+require_relative "signal/symptom"
+require_relative "signal/symptoms"
+require_relative "signal/failure"
+require_relative "signal/group"
+require_relative "signal/grouper"
+require_relative "signal/cluster"
+require_relative "signal/clusterer"
+require_relative "signal/report"
+require_relative "signal/configuration"
+require_relative "signal/reporters/related_failures"
+require_relative "signal/reporters/markdown"
+require_relative "signal/reporters/json_report"
+require_relative "signal/reporters/full_output"
+require_relative "signal/writer"
+require_relative "signal/parallel_run"
+require_relative "signal/parallel_merger"
+require_relative "signal/failure_builder"
+require_relative "signal/formatter"
+require_relative "signal/integrations/capybara"
+
+module RSpec
+  # Turns noisy RSpec failures into compact, high-signal diagnostic artifacts
+  # designed to be handed to an AI coding agent.
+  module Signal
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration if block_given?
+        configuration.reset_memoized!
+        configuration
+      end
+
+      # Registers the formatter and optional integrations.
+      #
+      # Called automatically when you `require "rspec/signal"` inside an
+      # `RSpec.configure` block or from `spec_helper.rb`. Safe to call twice.
+      #
+      # @return [Boolean] whether anything was installed
+      def install!(rspec_config = ::RSpec.configuration)
+        return false if @installed
+
+        @installed = true
+        return false unless configuration.enabled?
+
+        quiet_mode? # Capture CLI intent before RSpec finishes parsing ARGV.
+        loader = rspec_config.formatter_loader
+        unless loader.formatters.any?(Formatter)
+          rspec_config.add_formatter(Formatter)
+          @auto_installed = true
+        end
+
+        install_integrations!(rspec_config)
+        true
+      rescue StandardError => e
+        warn "rspec-signal: could not install (#{e.class}: #{e.message})"
+        false
+      end
+
+      def installed? = !!@installed
+
+      # True when we added the formatter ourselves rather than the user asking
+      # for it with `--format`. Only then do we put RSpec's default formatter
+      # back, because only then did we displace it.
+      def auto_installed? = !!@auto_installed
+
+      # Explicit formatter selection happens after --require files are loaded,
+      # so install! may initially look automatic. Detect the user's intent from
+      # the original CLI arguments (or the wrapper's explicit marker) at start
+      # time, after RSpec has finished configuring its formatter loader.
+      def quiet_mode?
+        return true if ENV["RSPEC_SIGNAL_QUIET"] == "1"
+        return @quiet_mode_requested if defined?(@quiet_mode_requested)
+
+        @quiet_mode_requested = formatter_arguments.intersect?(["RSpec::Signal::Formatter", "signal"])
+      end
+
+      # Adding any formatter suppresses RSpec's default one. When rspec-signal
+      # installed itself the user did not ask for that, so restore normal
+      # terminal feedback.
+      def restore_default_formatter!(rspec_config = ::RSpec.configuration)
+        loader = rspec_config.formatter_loader
+        return if loader.formatters.any? { |formatter| primary_output_formatter?(formatter) }
+
+        before = loader.formatters.dup
+        loader.add(loader.default_formatter, rspec_config.output_stream)
+        (loader.formatters - before).each do |formatter|
+          formatter.start(::RSpec::Core::Notifications::StartNotification.new(0, 0)) if formatter.respond_to?(:start)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # Versions worth recording in the report header.
+      def environment
+        versions = { "ruby" => RUBY_VERSION, "rspec" => ::RSpec::Core::Version::STRING }
+        versions["rails"] = ::Rails::VERSION::STRING if defined?(::Rails::VERSION::STRING)
+        versions["capybara"] = ::Capybara::VERSION if defined?(::Capybara::VERSION)
+        versions
+      rescue StandardError
+        { "ruby" => RUBY_VERSION }
+      end
+
+      # @api private Test support.
+      def reset!
+        @installed = false
+        @auto_installed = false
+        remove_instance_variable(:@quiet_mode_requested) if defined?(@quiet_mode_requested)
+        @configuration = nil
+      end
+
+      private
+
+      def formatter_arguments
+        ARGV.each_with_index.filter_map do |argument, index|
+          next ARGV[index + 1] if ["--format", "-f"].include?(argument)
+          next ::Regexp.last_match(1) if argument =~ /\A--format=(.+)\z/
+
+          argument[2..] if argument.start_with?("-f") && argument.length > 2
+        end
+      end
+
+      def install_integrations!(rspec_config)
+        return unless configuration.capture_capybara
+
+        Integrations::Capybara.install!(rspec_config, configuration)
+      end
+
+      # Formatters that give the developer their normal terminal feedback.
+      def primary_output_formatter?(formatter)
+        return false if formatter.is_a?(Formatter)
+
+        name = formatter.class.name.to_s
+        !name.end_with?("DeprecationFormatter", "FallbackMessageFormatter", "ProfileFormatter")
+      end
+    end
+  end
+end
+
+RSpec::Signal.install! if defined?(RSpec) && RSpec.respond_to?(:configuration)

data/lib/rspec-signal.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rspec/signal"

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: rspec-signal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chad Snow
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-08-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: |
+  rspec-signal is a deterministic context-reduction layer between RSpec and an AI
+  coding agent. It collapses framework and runtime backtrace plumbing, keeps
+  first-party frames plus the small amount of library context that explains the
+  failing operation, groups repeated failures into distinct signatures, and writes
+  a compact Markdown report you can hand straight to a coding agent.
+email:
+- chaddsnow@gmail.com
+executables:
+- rspec-signal
+- rspec-signal-parallel
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/rspec-signal
+- exe/rspec-signal-parallel
+- lib/rspec-signal.rb
+- lib/rspec/signal.rb
+- lib/rspec/signal/backtrace/classifier.rb
+- lib/rspec/signal/backtrace/frame.rb
+- lib/rspec/signal/backtrace/parser.rb
+- lib/rspec/signal/backtrace/reducer.rb
+- lib/rspec/signal/cluster.rb
+- lib/rspec/signal/clusterer.rb
+- lib/rspec/signal/configuration.rb
+- lib/rspec/signal/failure.rb
+- lib/rspec/signal/failure_builder.rb
+- lib/rspec/signal/fingerprint.rb
+- lib/rspec/signal/formatter.rb
+- lib/rspec/signal/group.rb
+- lib/rspec/signal/grouper.rb
+- lib/rspec/signal/html_summary.rb
+- lib/rspec/signal/integrations/capybara.rb
+- lib/rspec/signal/message.rb
+- lib/rspec/signal/parallel_merger.rb
+- lib/rspec/signal/parallel_run.rb
+- lib/rspec/signal/project.rb
+- lib/rspec/signal/redactor.rb
+- lib/rspec/signal/report.rb
+- lib/rspec/signal/reporters/full_output.rb
+- lib/rspec/signal/reporters/json_report.rb
+- lib/rspec/signal/reporters/markdown.rb
+- lib/rspec/signal/reporters/related_failures.rb
+- lib/rspec/signal/symptom.rb
+- lib/rspec/signal/symptoms.rb
+- lib/rspec/signal/symptoms/exception_class.rb
+- lib/rspec/signal/symptoms/http_status.rb
+- lib/rspec/signal/symptoms/record.rb
+- lib/rspec/signal/symptoms/route.rb
+- lib/rspec/signal/symptoms/ruby_error.rb
+- lib/rspec/signal/symptoms/selector.rb
+- lib/rspec/signal/version.rb
+- lib/rspec/signal/writer.rb
+homepage: https://github.com/SilenceDogood1984/rspec-signal
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/SilenceDogood1984/rspec-signal
+  changelog_uri: https://github.com/SilenceDogood1984/rspec-signal/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/SilenceDogood1984/rspec-signal/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: Turn noisy RSpec failures into compact, high-signal reports for AI coding
+  agents.
+test_files: []