rspec-signal 0.1.0

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

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Reporters
+      # Renders the primary artifact: a compact, model-neutral Markdown report.
+      #
+      # Deliberately contains no instructions to the reader. It is a diagnostic
+      # document, not a prompt, so it works the same pasted into any assistant or
+      # read by a human.
+      class Markdown
+        FENCE = "```"
+        MAX_RERUN_ARGUMENTS = 10
+
+        DIAGNOSTIC_LABELS = {
+          url: "URL", path: "Path", title: "Page title", status_code: "Status",
+          driver: "Driver", console: "Console", screenshot: "Screenshot", saved_page: "Saved HTML"
+        }.freeze
+
+        def initialize(report, config)
+          @report = report
+          @config = config
+        end
+
+        def render
+          sections = [header]
+          sections << outside_examples_notice
+          # Themes before the inventory: what an agent needs first is the
+          # possibility that thirty-five signatures are five problems.
+          sections << related_section
+          sections << index if @report.group_count > 1
+          sections.concat(rendered_groups)
+          sections << footer
+          "#{sections.compact.join("\n\n").rstrip}\n"
+        end
+
+        private
+
+        def header
+          lines = ["# RSpec Signal", "", headline]
+          lines << reduction_line if @report.total_frames.positive?
+          lines << "" << meta_line
+          lines << "" << conventions
+          lines.join("\n")
+        end
+
+        def headline
+          parts = [quantity(@report.example_count, "example"), quantity(@report.failure_count, "failure")]
+          parts << "#{number(@report.pending_count)} pending" if @report.pending_count.positive?
+          parts << "#{number(@report.group_count)} distinct #{plural(@report.group_count, "signature")}"
+          parts << "#{number(@report.cluster_count)} related #{plural(@report.cluster_count, "cluster")}" \
+            if @report.cluster_count.positive?
+          parts << outside_examples_count if @report.errors_outside_examples.positive?
+          "**#{parts.join(" | ")}**"
+        end
+
+        def outside_examples_count = "#{quantity(@report.errors_outside_examples, "error")} outside examples"
+
+        def quantity(value, word) = "#{number(value)} #{plural(value, word)}"
+
+        def reduction_line
+          "Backtraces reduced from #{number(@report.total_frames)} to " \
+            "#{number(@report.kept_frames)} frames " \
+            "(#{number(@report.omitted_frames)} framework/library #{plural(@report.omitted_frames, "frame")} omitted)."
+        end
+
+        def meta_line
+          bits = []
+          bits << "seed `#{@report.seed}`" if @report.seed_used?
+          bits << "#{@report.duration.round(2)}s" if @report.duration
+          @report.environment.each { |name, version| bits << "#{name} #{version}" }
+          bits << "rspec-signal #{VERSION}"
+          bits.join(" | ")
+        end
+
+        def conventions
+          "Trace frames are innermost first. Project paths are relative to the repository root; " \
+            "third-party frames appear as `gem/path.rb:line`."
+        end
+
+        def index
+          rows = groups.each_with_index.map do |group, position|
+            "| #{position + 1} | #{group.size} | `#{group.exception_class}` | " \
+              "#{escape(group.fingerprint.culprit)} | #{escape(one_line(group.message.headline(90)))} |"
+          end
+          ["## Signatures", "",
+           "| # | Examples | Exception | Raised in | Message |",
+           "|--:|---------:|-----------|-----------|---------|",
+           *rows].join("\n")
+        end
+
+        def related_section
+          RelatedFailures.new(@report.clusters, signature_positions, @config).render
+        end
+
+        # Cluster members point back at the numbered sections below, so the
+        # reader can go straight from a symptom to the failures carrying it.
+        def signature_positions
+          @signature_positions ||= @report.groups.each_with_index.to_h { |group, i| [group.fingerprint.digest, i + 1] }
+        end
+
+        # A `before(:suite)` blow-up produces no failed examples at all. RSpec
+        # only reports those through its message stream, which a formatter
+        # cannot capture without swallowing every other message, so say plainly
+        # what happened and where to look.
+        def outside_examples_notice
+          return nil unless @report.errors_outside_examples.positive?
+
+          count = @report.errors_outside_examples
+          ["## Errors outside examples", "",
+           "#{number(count)} #{plural(count, "error")} occurred outside of any example " \
+           "(a `before(:suite)` hook, a spec file that failed to load, or similar). " \
+           "rspec-signal cannot capture their detail; the full text is in RSpec's own output."].join("\n")
+        end
+
+        def rendered_groups
+          rendered = groups.each_with_index.map { |group, position| group_section(group, position + 1) }
+          if truncated_groups.positive?
+            rendered << "_#{truncated_groups} further #{plural(truncated_groups, "signature")} " \
+                        "not rendered (see `signal.json`)._"
+          end
+          rendered
+        end
+
+        def group_section(group, position)
+          sections = [
+            heading(group, position),
+            fenced(group.message.body(max_lines: @config.max_message_lines,
+                                      max_diff_lines: @config.max_diff_lines)),
+            locators(group).join("\n"),
+            labelled("Trace", fenced(trace_lines(group.representative))),
+            diagnostics_section(group.representative),
+            labelled("Rerun", fenced(rerun_commands(group), "bash")),
+            affected_section(group)
+          ]
+          sections.compact.join("\n\n")
+        end
+
+        def heading(group, position)
+          ["## #{position}. #{group.exception_class}#{count_suffix(group)}", "",
+           "> #{one_line(group.representative.description)}"].join("\n")
+        end
+
+        def labelled(label, body) = "**#{label}**\n\n#{body}"
+
+        # The representative on its own, plus the whole signature when that is a
+        # different command and short enough to be worth typing.
+        def rerun_commands(group)
+          commands = ["bundle exec rspec #{group.representative.rerun}"]
+          arguments = group.failures.map(&:rerun).uniq
+          if arguments.size > 1 && arguments.size <= MAX_RERUN_ARGUMENTS
+            commands << "bundle exec rspec #{arguments.join(" ")}"
+          end
+          commands
+        end
+
+        def count_suffix(group)
+          return "" if group.size == 1
+
+          " -- #{group.size} examples"
+        end
+
+        def locators(group)
+          failure = group.representative
+          seen = [failure.spec_location]
+          lines = ["- Example `#{failure.spec_location}`"]
+
+          app_context = group.fingerprint.app_context
+          if app_context && !seen.include?(app_context)
+            lines << "- Your code `#{app_context}`"
+            seen << app_context
+          end
+
+          culprit = group.fingerprint.culprit
+          if culprit && !seen.include?(culprit)
+            gem_name = culprit_frame(failure)&.gem_name
+            lines << "- Raised in `#{culprit}`#{" (#{gem_name})" if gem_name}"
+          end
+
+          failure.shared_group_locations.first(3).each do |location|
+            lines << "- Via shared example group #{location}"
+          end
+
+          if failure.reduced.fallback?
+            lines << "- No first-party frames in this backtrace; innermost frames shown instead"
+          end
+
+          lines
+        end
+
+        # The same frame the fingerprint calls the culprit, so the gem label
+        # beside a location always belongs to that location.
+        def culprit_frame(failure) = failure.frames.reject(&:framework?).first
+
+        def trace_lines(failure)
+          entries = failure.reduced.entries.map(&:to_s)
+          return ["#{failure.spec_location}  (no backtrace available)"] if entries.empty?
+
+          entries
+        end
+
+        def diagnostics_section(failure)
+          items = failure.diagnostics.reject { |_, value| value.nil? || value.to_s.empty? }
+          return nil if items.empty?
+
+          rows = items.map { |key, value| "- #{humanize(key)}: #{format_diagnostic(value)}" }
+          labelled("Browser state", rows.join("\n"))
+        end
+
+        def format_diagnostic(value)
+          return value.map { |item| "`#{one_line(item)}`" }.join("; ") if value.is_a?(Array)
+
+          text = one_line(value)
+          text.length > 300 ? "`#{text[0, 297]}...`" : "`#{text}`"
+        end
+
+        def affected_section(group)
+          others = group.failures.reject { |failure| failure.equal?(group.representative) }
+          return nil if others.empty?
+
+          grouped = others.group_by(&:spec_location)
+          shown = grouped.first(@config.max_affected_examples)
+          rows = shown.map { |location, failures| affected_row(location, failures) }
+          hidden = grouped.size - shown.size
+          rows << "... and #{hidden} more #{plural(hidden, "location")}" if hidden.positive?
+
+          labelled("Also failing identically (#{others.size})", fenced(rows))
+        end
+
+        # Parameterised examples all share one `it` line. Listing that line once
+        # with a count says the same thing in a fraction of the space.
+        def affected_row(location, failures)
+          return "#{location}  #{one_line(failures.first.description)}" if failures.size == 1
+
+          "#{location}  (#{failures.size} examples)"
+        end
+
+        def footer
+          notes = ["---", "",
+                   "Generated by [rspec-signal](https://github.com/SilenceDogood1984/rspec-signal). " \
+                   "Backtrace frames from the test runner, loader and CLI are removed; " \
+                   "first-party frames and the library frames adjacent to them are kept."]
+          notes << "Review this file before sharing it: it can contain application data." if @config.redact?
+          notes.join("\n")
+        end
+
+        def groups
+          @groups ||= @config.max_groups ? @report.groups.first(@config.max_groups) : @report.groups
+        end
+
+        def truncated_groups = @report.group_count - groups.size
+
+        def fenced(lines, language = "text")
+          [FENCE + language, *Array(lines), FENCE].join("\n")
+        end
+
+        def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+
+        def escape(text) = text.to_s.gsub("|", "\\|")
+
+        def humanize(key)
+          DIAGNOSTIC_LABELS.fetch(key.to_sym) { key.to_s.tr("_", " ").capitalize }
+        end
+
+        def plural(count, word) = count == 1 ? word : "#{word}s"
+
+        def number(value) = value.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Reporters
+      # The "Related failures" section of the Markdown report.
+      #
+      # The second, looser grouping layer. A signature says "these failures are
+      # the same failure"; a cluster says only "these share one strong
+      # diagnostic symptom, so look at them together". The section says so in
+      # those words, because the difference is the whole point: a reader who
+      # takes a cluster for a root cause has been misled.
+      #
+      # Kept to a few lines per cluster. This layer exists to save the reader
+      # from reading thirty-five signature sections, and it would be a poor
+      # trade if it cost thirty-five sections' worth of prose to do it.
+      class RelatedFailures
+        MAX_SYMPTOMS = 4
+        MAX_SIGNATURES = 8
+
+        PREAMBLE = "Failures sharing one diagnostic symptom across more than one signature. " \
+                   "Weaker than a signature: a likely common cause, not a proven identical failure. " \
+                   "The signatures below remain authoritative."
+
+        # @param clusters [Array<Cluster>]
+        # @param signature_positions [Hash{String => Integer}] digest => index in the report
+        def initialize(clusters, signature_positions, config)
+          @clusters = clusters
+          @signature_positions = signature_positions
+          @config = config
+        end
+
+        # @return [String, nil] nil when nothing relates, so the section vanishes
+        def render
+          return nil if shown.empty?
+
+          blocks = shown.each_with_index.map { |cluster, position| block(cluster, position + 1) }
+          blocks << truncation_note if hidden.positive?
+          [["## Related failures", "", PREAMBLE].join("\n"), *blocks].join("\n\n")
+        end
+
+        private
+
+        def shown
+          @shown ||= @config.max_clusters ? @clusters.first(@config.max_clusters) : @clusters
+        end
+
+        def hidden = @clusters.size - shown.size
+
+        def truncation_note
+          "_#{hidden} further related #{plural(hidden, "cluster")} not rendered (see `signal.json`)._"
+        end
+
+        def block(cluster, position)
+          lines = [heading(cluster, position), ""]
+          # Only worth a line when the symptom took more than one wording: with
+          # one, the heading already said it.
+          lines << "- Symptoms: #{symptoms(cluster)}" if cluster.symptom_counts.size > 1
+          lines << "- Specs: #{specs(cluster)}"
+          lines << "- Signatures: #{signatures(cluster)}"
+          lines.join("\n")
+        end
+
+        def heading(cluster, position)
+          "### R#{position}. #{sentence(cluster.label)} -- " \
+            "#{cluster.size} #{plural(cluster.size, "example")} across " \
+            "#{cluster.signature_count} #{plural(cluster.signature_count, "signature")}"
+        end
+
+        def symptoms(cluster)
+          listing(cluster.symptom_counts.keys, MAX_SYMPTOMS, cluster.symptom_counts) do |detail, count|
+            "`#{one_line(detail)}`#{" (#{count})" if count}"
+          end
+        end
+
+        def specs(cluster)
+          listing(cluster.spec_files, @config.max_cluster_specs) { |path, _| "`#{path}`" }
+        end
+
+        def signatures(cluster)
+          positions = cluster.signatures.filter_map { |digest| @signature_positions[digest] }.sort
+          listing(positions, MAX_SIGNATURES) { |position, _| "##{position}" }
+        end
+
+        def listing(items, limit, counts = nil)
+          visible = items.first(limit)
+          rendered = visible.map { |item| yield(item, counts&.fetch(item, nil)) }
+          remaining = items.size - visible.size
+          rendered << "and #{remaining} more" if remaining.positive?
+          rendered.join(", ")
+        end
+
+        def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+
+        def sentence(text) = text.to_s.sub(/\A[a-z]/, &:upcase)
+
+        def plural(count, word) = count == 1 ? word : "#{word}s"
+      end
+    end
+  end
+end

data/lib/rspec/signal/symptom.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    # One strong diagnostic characteristic pulled out of a failure message.
+    #
+    # Symptoms are what the looser "related failures" layer clusters on, and
+    # they are deliberately narrow. Every extractor is anchored on a specific
+    # phrase produced by a specific library -- an HTTP status mismatch, a
+    # missing selector, a route that does not exist -- never on two messages
+    # merely resembling each other. A failure that matches nothing has no
+    # symptom and joins no cluster, which is the safe direction to be wrong in.
+    #
+    #   kind    :http_status, :selector, ...  -- which extractor fired
+    #   key     the cluster identity; equal keys mean "same symptom"
+    #   label   the cluster heading, already human-readable
+    #   detail  this failure's own wording of the symptom, for the symptom list
+    Symptom = Struct.new(:kind, :key, :label, :detail, keyword_init: true) do
+      def to_h = { kind: kind, key: key, label: label, detail: detail }
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Symptoms
+      # The last resort: cluster on the exception class itself.
+      #
+      # This is the one that would wreck the report if it were applied
+      # generally, so it is applied narrowly. It fires only for a *namespaced*
+      # class -- `PG::ConnectionBad`, `Errno::ECONNREFUSED` -- which is
+      # specific enough that seeing it twice is a fact worth reporting. Bare
+      # classes like RuntimeError and ArgumentError say nothing about cause and
+      # are refused outright, and so is every class an earlier, finer extractor
+      # is responsible for, so that a Capybara lookup with an unparseable
+      # message cannot fall through and drag unrelated selectors in with it.
+      module ExceptionClass
+        GENERIC = %w[
+          RuntimeError StandardError Exception ScriptError ArgumentError TypeError NameError
+          NoMethodError NotImplementedError IndexError KeyError RangeError IOError EOFError
+          FrozenError LocalJumpError StopIteration ZeroDivisionError SystemStackError
+          LoadError SyntaxError SecurityError ThreadError FiberError
+        ].freeze
+
+        # Owned by an earlier extractor; never eligible here.
+        CLAIMED = %w[
+          RSpec::
+          Capybara::ElementNotFound Capybara::ExpectationNotMet
+          ActiveRecord::RecordNotFound ActiveRecord::RecordInvalid
+          ActionController::RoutingError ActionController::UrlGenerationError
+        ].freeze
+
+        module_function
+
+        def call(failure, _text)
+          name = failure.exception_class.to_s
+          return nil unless name.include?("::")
+          return nil if GENERIC.include?(name)
+          return nil if CLAIMED.any? { |prefix| name.start_with?(prefix) }
+
+          Symptom.new(kind: :exception_class, key: "exception:#{name}",
+                      label: "`#{name}` raised in several places", detail: name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Symptoms
+      # An HTTP status the application returned but the spec did not expect.
+      #
+      # Clustered on the *actual* status, because that is the fact with a shared
+      # cause: eight specs that each wanted something different and all got 404
+      # are eight symptoms of one broken route. The expected side survives only
+      # as this failure's detail line, so a cluster can still show that some
+      # examples wanted 200 and others wanted a redirect.
+      module HttpStatus
+        # One side of a status mismatch: `404`, `:not_found`, `:ok (200)`.
+        CODE = /:?[\w-]+(?: \(\d{3}\))?/
+
+        PATTERNS = [
+          # rspec-rails `have_http_status(200)` / `have_http_status(:ok)`
+          /expected the response to have status code (?<expected>#{CODE}) *,? *but it was (?<actual>#{CODE})/i,
+          # rspec-rails `have_http_status(:success)` / `:redirect` / `:error` / `:missing`
+          /expected the response to have an? (?<expected>\w+) status code \([^)]*\) *,? *but it was (?<actual>#{CODE})/i, # rubocop:disable Layout/LineLength
+          # Rails' own `assert_response`
+          /expected response to be a <(?<expected>[^>]+)>, *but was a <(?<actual>[^>]+)>/i,
+          # The shorthand several house matchers use
+          /expected(?: the)? response status (?:to be )?(?<expected>:?[\w-]+) *,? *(?:but )?got:? *(?<actual>:?[\w-]+)/i
+        ].freeze
+
+        # Enough of the standard set to name the common ones. An unrecognised
+        # code still clusters, it just does not get a friendly name.
+        NAMES = {
+          "200" => "OK", "201" => "Created", "204" => "No Content", "301" => "Moved Permanently",
+          "302" => "Found", "304" => "Not Modified", "400" => "Bad Request", "401" => "Unauthorized",
+          "403" => "Forbidden", "404" => "Not Found", "406" => "Not Acceptable", "409" => "Conflict",
+          "422" => "Unprocessable Entity", "429" => "Too Many Requests",
+          "500" => "Internal Server Error", "502" => "Bad Gateway", "503" => "Service Unavailable"
+        }.freeze
+
+        CODES = {
+          "ok" => "200", "created" => "201", "no_content" => "204", "moved_permanently" => "301",
+          "found" => "302", "not_modified" => "304", "bad_request" => "400", "unauthorized" => "401",
+          "forbidden" => "403", "not_found" => "404", "not_acceptable" => "406", "conflict" => "409",
+          "unprocessable_entity" => "422", "unprocessable_content" => "422", "too_many_requests" => "429",
+          "internal_server_error" => "500", "bad_gateway" => "502", "service_unavailable" => "503"
+        }.freeze
+
+        module_function
+
+        GENERIC_EXPECTATION = /expected:\s*(?<expected>\d{3})\s+got:\s*(?<actual>\d{3})/i
+        STATUS_EXPRESSION = /(?:response\s*\.\s*status|response\s*\.\s*status_code|response\s*\[\s*:status\s*\])/i
+
+        def call(failure, text)
+          match = PATTERNS.filter_map { |pattern| pattern.match(text) }.first
+          match ||= generic_expectation(failure, text)
+          return nil unless match
+
+          actual = code(match[:actual])
+          return nil unless actual
+
+          Symptom.new(kind: :http_status, key: "http-status:#{actual}", label: label(actual),
+                      detail: "expected #{token(match[:expected])}, got #{actual}")
+        end
+
+        # RSpec's generic equality matcher does not mention HTTP in its
+        # expected/got lines. Only accept it when the captured failing
+        # expression explicitly reads a response status, avoiding arbitrary
+        # three-digit numeric comparisons.
+        def generic_expectation(failure, text)
+          return nil unless STATUS_EXPRESSION.match?(failure.message.text.to_s)
+
+          GENERIC_EXPECTATION.match(text)
+        end
+
+        def label(actual)
+          name = NAMES[actual]
+          "unexpected #{actual}#{" (#{name})" if name} responses"
+        end
+
+        # The numeric code, whether it arrived as a number, a symbol, or both.
+        def code(raw)
+          text = raw.to_s
+          return ::Regexp.last_match(1) if text =~ /(\d{3})/
+
+          CODES[text.delete_prefix(":").downcase]
+        end
+
+        # How to word one side of the mismatch: a code where there is one, and
+        # otherwise the word the matcher used -- `redirect`, `success`.
+        def token(raw)
+          text = raw.to_s.strip
+          return ::Regexp.last_match(1) if text =~ /(\d{3})/
+
+          bare = text.delete_prefix(":").downcase
+          CODES[bare] || bare
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Symptoms
+      # ActiveRecord shapes: a model that has no rows, a validation that keeps
+      # failing, a column or table the schema does not have.
+      #
+      # The model, the validation sentence and the missing identifier are the
+      # cluster keys. A `RecordNotFound` for `User` and one for `Order` are two
+      # different problems and stay apart.
+      module Record
+        NOT_FOUND  = /Couldn't find (?<model>[A-Z]\w*(?:::\w+)*)/
+        VALIDATION = %r{Validation failed: (?<detail>.{1,120}?)(?=\s{2,}|\s+Caused by\b|\s+Failure/Error\b|\z)}
+        MISSING    = /(?<what>column|relation|table)\s+["'`]?(?<name>[\w."]+?)["'`]?\s+does not exist/i
+        SQLITE     = /no such (?<what>column|table):\s*(?<name>[\w.]+)/i
+
+        module_function
+
+        def call(_failure, text)
+          not_found(text) || schema(text) || validation(text)
+        end
+
+        def not_found(text)
+          match = NOT_FOUND.match(text)
+          return nil unless match
+
+          model = match[:model]
+          Symptom.new(kind: :record_not_found, key: "record-not-found:#{model}",
+                      label: "missing `#{model}` records", detail: "no #{model} found")
+        end
+
+        def schema(text)
+          match = MISSING.match(text) || SQLITE.match(text)
+          return nil unless match
+
+          what = match[:what].downcase
+          name = match[:name].delete('"')
+          Symptom.new(kind: :schema, key: "schema:#{what}:#{name}",
+                      label: "missing database #{what} `#{name}`", detail: "#{what} #{name} does not exist")
+        end
+
+        def validation(text)
+          match = VALIDATION.match(text)
+          return nil unless match
+
+          detail = match[:detail].strip.sub(/[.,]\z/, "")
+          return nil if detail.empty?
+
+          Symptom.new(kind: :validation, key: "validation:#{detail.downcase}",
+                      label: "validation failure `#{detail}`", detail: detail)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Signal
+    module Symptoms
+      # A route that does not exist -- the usual thing sitting behind a suite
+      # full of unexplained 404s.
+      module Route
+        NO_ROUTE = /No route matches (?<target>\[[A-Z]+\]\s*"[^"]*"|\{[^}]*\})/
+        # `reader_progress_path` after the route was renamed or removed.
+        HELPER = /undefined (?:local variable or method|method) [`'"](?<helper>\w+_(?:path|url))['"`]/
+
+        module_function
+
+        def call(_failure, text)
+          match = NO_ROUTE.match(text)
+          return helper(text) unless match
+
+          target = normalize(match[:target])
+          Symptom.new(kind: :route, key: "route:#{target}",
+                      label: "no route matches `#{target}`", detail: "no route matches #{target}")
+        end
+
+        def helper(text)
+          match = HELPER.match(text)
+          return nil unless match
+
+          name = match[:helper]
+          Symptom.new(kind: :route_helper, key: "route-helper:#{name}",
+                      label: "undefined route helper `#{name}`", detail: "undefined `#{name}`")
+        end
+
+        # `/readers/48213/progress` and `/readers/91055/progress` are the same
+        # missing route, so identifier-shaped segments become `:id`.
+        def normalize(target)
+          target.to_s
+                .gsub(%r{/\d+(?=/|"|\z)}, "/:id")
+                .gsub(%r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=/|"|\z)}i, "/:id")
+                .gsub(/\s+/, " ")
+                .strip
+        end
+      end
+    end
+  end
+end