ibex 0.3.0 → 0.4.0

data/lib/ibex/impact/automaton_impact.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Impact
+    # Maps propagated grammar symbols to parser states and conflict changes.
+    class AutomatonImpact
+      # @rbs @automaton: IR::Automaton
+      # @rbs @symbol_ids: Array[Integer]
+      # @rbs @production_ids: Array[Integer]
+      attr_reader :affected_states #: Array[Integer]
+      attr_reader :production_ids #: Array[Integer]
+      attr_reader :conflict_states #: Array[Integer]
+
+      # @rbs (IR::Automaton automaton, Array[Integer]) -> void
+      def initialize(automaton, symbol_ids)
+        @automaton = automaton
+        @symbol_ids = symbol_ids.uniq.sort #: Array[Integer]
+        @production_ids = affected_productions
+        @affected_states = affected_state_ids
+        @conflict_states = conflict_state_ids
+        freeze
+      end
+
+      # @rbs (Hash[Symbol, Object?] diff) -> Hash[Symbol, Object?]
+      def conflict_changes(diff)
+        diff.fetch(:conflicts) #: Hash[Symbol, Object?]
+      end
+
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
+        { states: @affected_states, productions: @production_ids, conflict_states: @conflict_states }
+      end
+
+      private
+
+      # @rbs () -> Array[Integer]
+      def affected_productions
+        @automaton.grammar.productions.filter_map do |production|
+          production.id if @symbol_ids.include?(production.lhs) || production.rhs.any? { |id| @symbol_ids.include?(id) }
+        end.sort
+      end
+
+      # @rbs () -> Array[Integer]
+      def affected_state_ids
+        @automaton.states.filter_map do |state|
+          state.id if state.items.any? { |item| @production_ids.include?(item.production) }
+        end.sort
+      end
+
+      # @rbs () -> Array[Integer]
+      def conflict_state_ids
+        @automaton.states.filter_map { |state| state.id unless state.conflicts.empty? }.sort
+      end
+    end
+  end
+end

data/lib/ibex/impact/coverage_impact.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Impact
+    # Selects separated runtime coverage reports for affected productions.
+    class CoverageImpact
+      attr_reader :status #: String
+      attr_reader :reports #: Array[Hash[Symbol, Object?]]
+      attr_reader :warnings #: Array[String]
+
+      # @rbs (IR::Automaton automaton, Array[Integer], Array[[String, Coverage::Report]]) -> void
+      def initialize(automaton, production_ids, reports)
+        @automaton = automaton
+        @production_ids = production_ids.sort
+        @warnings = []
+        @reports = select_reports(reports)
+        @status = coverage_status(reports)
+        freeze
+      end
+
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
+        { status: @status, reports: @reports }
+      end
+
+      private
+
+      # @rbs (Array[[String, Coverage::Report]]) -> Array[Hash[Symbol, Object?]]
+      def select_reports(reports)
+        selected = reports.filter_map do |path, report|
+          unless report.grammar_digest == @automaton.grammar_digest
+            @warnings << "#{path}: coverage grammar digest does not match the analysis input; report ignored"
+            next
+          end
+
+          hits = report.production_hits.keys & @production_ids
+          next if hits.empty?
+
+          { path: path, productions: hits.sort }
+        end
+        selected.sort_by { |entry| entry.fetch(:path) }
+      end
+
+      # @rbs (Array[[String, Coverage::Report]]) -> String
+      def coverage_status(reports)
+        return "not_requested" if reports.empty?
+
+        @reports.empty? ? "unmatched" : "matched"
+      end
+    end
+  end
+end

data/lib/ibex/impact/graph.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "../analysis"
+
+module Ibex
+  module Impact
+    # A grammar dependency edge with enough origin information for a witness.
+    class Edge
+      attr_reader :source #: Integer
+      attr_reader :target #: Integer
+      attr_reader :kind #: Symbol
+      attr_reader :production #: Integer?
+      attr_reader :position #: Integer?
+
+      # @rbs (source: Integer, target: Integer, kind: Symbol, production: Integer?, position: Integer?) -> void
+      def initialize(source:, target:, kind:, production: nil, position: nil)
+        @source = source
+        @target = target
+        @kind = kind.to_sym
+        @production = production
+        @position = position
+        freeze
+      end
+
+      # @rbs () -> Array[Integer | Symbol | nil]
+      def sort_key
+        [@source, @target, @production || -1, @position || -1, @kind]
+      end
+    end
+
+    # Combines reference, FIRST, and FOLLOW propagation dependencies.
+    class Graph
+      EDGE_KINDS = %i[reference first follow_lhs follow_first].freeze #: Array[Symbol]
+      KIND_ALIASES = {
+        all: EDGE_KINDS, reference: [:reference], first: [:first], follow: %i[follow_lhs follow_first],
+        follow_lhs: [:follow_lhs], follow_first: [:follow_first]
+      }.freeze #: Hash[Symbol, Array[Symbol]]
+
+      attr_reader :grammar #: IR::Grammar
+      attr_reader :sets #: Analysis::Sets
+
+      # @rbs (IR::Grammar grammar, ?sets: Analysis::Sets) -> void
+      def initialize(grammar, sets: nil)
+        @grammar = grammar
+        @sets = sets || Analysis::Sets.new(grammar)
+        @edges = build_edges
+        freeze_edges
+      end
+
+      # @rbs (?Symbol kind) -> untyped
+      def edges(kind = :all)
+        selected = KIND_ALIASES.fetch(kind.to_sym) { raise ArgumentError, "unknown impact edge kind #{kind}" }
+        return selected.flat_map { |name| @edges.fetch(name) }.sort_by(&:sort_key) if selected.length > 1
+
+        @edges.fetch(selected.fetch(0))
+      end
+
+      # @rbs (Symbol kind) -> Array[Array[Integer]]
+      def adjacency(kind)
+        result = Array.new(@grammar.symbols.length) { [] }
+        edges(kind).each { |edge| result[edge.source] << edge.target }
+        result.each(&:uniq!)
+        result
+      end
+
+      private
+
+      # @rbs () -> Hash[Symbol, Array[Edge]]
+      def build_edges
+        result = EDGE_KINDS.to_h { |kind| [kind, []] }
+        @grammar.productions.each do |production|
+          add_production_edges(result, production)
+        end
+        result.each_value { |edges| edges.sort_by!(&:sort_key) }
+        result
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production) -> void
+      def add_production_edges(result, production)
+        production.rhs.each_with_index do |symbol_id, position|
+          next unless @grammar.symbol_by_id(symbol_id)&.nonterminal?
+
+          result[:reference] << edge(symbol_id, production.lhs, :reference, production, position)
+          add_first_edge(result, production, symbol_id, position)
+          add_follow_edges(result, production, symbol_id, position)
+        end
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production, Integer, Integer) -> void
+      def add_first_edge(result, production, symbol_id, position)
+        prefix = production.rhs[0...position] || []
+        return unless @sets.sequence_nullable?(prefix)
+        return unless @sets.first_dependencies.fetch(symbol_id).include?(production.lhs)
+
+        result[:first] << edge(symbol_id, production.lhs, :first, production, position)
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production, Integer, Integer) -> void
+      def add_follow_edges(result, production, symbol_id, position)
+        suffix = production.rhs[(position + 1)..] || []
+        if @sets.sequence_nullable?(suffix) && @sets.follow_dependencies.fetch(production.lhs).include?(symbol_id)
+          result[:follow_lhs] << edge(production.lhs, symbol_id, :follow_lhs, production, position)
+        end
+        add_follow_first_edges(result, production, symbol_id, position)
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production, Integer, Integer) -> void
+      def add_follow_first_edges(result, production, symbol_id, position)
+        suffix = production.rhs[(position + 1)..] || []
+        suffix.each_with_index do |candidate, offset|
+          candidate_prefix = suffix[0...offset] || []
+          break unless @sets.sequence_nullable?(candidate_prefix)
+          break unless @grammar.symbol_by_id(candidate)&.nonterminal?
+
+          result[:follow_first] << edge(candidate, symbol_id, :follow_first, production, position + 1 + offset)
+        end
+      end
+
+      # @rbs (Integer source, Integer target, Symbol kind, IR::Production production, Integer position) -> Edge
+      def edge(source, target, kind, production, position)
+        Edge.new(source: source, target: target, kind: kind, production: production.id, position: position)
+      end
+
+      # @rbs () -> void
+      def freeze_edges
+        @edges.each_value(&:freeze)
+        @edges.freeze
+      end
+    end
+  end
+end

data/lib/ibex/impact/propagation.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "graph"
+
+module Ibex
+  module Impact
+    # One shortest witness for a symbol reached by dependency propagation.
+    class Node
+      attr_reader :symbol #: Integer
+      attr_reader :distance #: Integer
+      attr_reader :witness #: Array[Edge]
+      attr_reader :kind #: Symbol
+      attr_reader :component #: Array[Integer]
+
+      # @rbs (symbol: Integer, distance: Integer, witness: Array[Edge], kind: Symbol, component: Array[Integer]) -> void
+      def initialize(symbol:, distance:, witness:, kind:, component:)
+        @symbol = symbol
+        @distance = distance
+        @witness = witness.freeze
+        @kind = kind
+        @component = component.freeze
+        freeze
+      end
+    end
+
+    # Performs deterministic forward propagation over a dependency graph.
+    class Propagation
+      # @rbs @graph: Graph
+      # @rbs (Graph graph) -> void
+      def initialize(graph)
+        @graph = graph
+      end
+
+      # @rbs (Array[Integer] seeds, Symbol kind, ?max_depth: Integer?) -> Hash[Integer, Node]
+      def propagate(seeds, kind = :all, max_depth: nil)
+        validate_depth(max_depth)
+        selected = normalize_seeds(seeds)
+        adjacency = @graph.adjacency(kind)
+        components = Analysis::Digraph.send(:strongly_connected_components, adjacency)
+        component_for = component_index(components, adjacency.length)
+        component_edges = component_adjacency(adjacency, component_for, components.length)
+        component_nodes = traverse_components(selected, component_for, component_edges, max_depth)
+        witnesses = symbol_witnesses(selected, adjacency, kind)
+        build_nodes(component_nodes, components, kind, witnesses)
+      end
+
+      alias call propagate
+
+      private
+
+      # @rbs (Integer?) -> void
+      def validate_depth(max_depth)
+        return if max_depth.nil? || (max_depth.is_a?(Integer) && max_depth >= 0)
+
+        raise ArgumentError, "impact depth must be a non-negative integer"
+      end
+
+      # @rbs (Array[Integer]) -> Array[Integer]
+      def normalize_seeds(seeds)
+        seeds.uniq.sort.each do |id|
+          unless @graph.grammar.symbol_by_id(id)
+            raise ArgumentError,
+                  "impact seed #{id.inspect} is not a grammar symbol"
+          end
+        end
+      end
+
+      # @rbs (Array[Array[Integer]], Integer) -> Array[Integer]
+      def component_index(components, size)
+        result = Array.new(size, 0) #: Array[Integer]
+        components.each_with_index { |members, id| members.each { |member| result[member] = id } }
+        result
+      end
+
+      # @rbs (Array[Array[Integer]], Array[Integer], Integer) -> Array[Array[Integer]]
+      def component_adjacency(adjacency, component_for, component_count)
+        result = Array.new(component_count) { [] } #: Array[Array[Integer]]
+        adjacency.each_with_index do |successors, source|
+          source_component = component_for.fetch(source)
+          successors.each do |target|
+            target_component = component_for.fetch(target)
+            next if source_component == target_component
+
+            result[source_component] << target_component
+          end
+        end
+        result.each do |successors|
+          successors.uniq!
+          successors.sort!
+        end
+        result
+      end
+
+      # @rbs (Array[Integer], Array[Integer], Array[Array[Integer]], Integer?) -> Hash[Integer, Integer]
+      def traverse_components(seeds, component_for, component_edges, max_depth)
+        queue = seeds.uniq.sort.map do |seed|
+          [component_for.fetch(seed), 0]
+        end #: Array[[Integer, Integer]]
+        result = {} #: Hash[Integer, Integer]
+        until queue.empty?
+          component, distance = queue.shift
+          next if result.key?(component)
+          next if max_depth && distance > max_depth
+
+          result[component] = distance
+          component_edges.fetch(component).each do |target|
+            queue << [target, distance + 1]
+          end
+        end
+        result
+      end
+
+      # @rbs (Array[Integer], Array[Array[Integer]], Symbol) -> Hash[Integer, Array[Edge]]
+      def symbol_witnesses(seeds, adjacency, kind)
+        edges = @graph.edges(kind).group_by { |edge| [edge.source, edge.target] }
+        queue = seeds.uniq.sort.map { |seed| [seed, []] } #: Array[[Integer, Array[Edge]]]
+        result = {} #: Hash[Integer, Array[Edge]]
+        until queue.empty?
+          symbol, witness = queue.shift
+          next if result.key?(symbol)
+
+          result[symbol] = witness
+          adjacency.fetch(symbol).each do |target|
+            edge = edges.fetch([symbol, target]).fetch(0)
+            queue << [target, witness + [edge]]
+          end
+        end
+        result
+      end
+
+      # @rbs (Hash[Integer, Integer], Array[Array[Integer]], Symbol, Hash[Integer, Array[Edge]]) -> Hash[Integer, Node]
+      def build_nodes(component_nodes, components, kind, witnesses)
+        result = {} #: Hash[Integer, Node]
+        component_nodes.each do |component, distance|
+          members = components.fetch(component).sort
+          members.each do |symbol|
+            result[symbol] = Node.new(
+              symbol: symbol, distance: distance, witness: witnesses.fetch(symbol), kind: kind, component: members
+            )
+          end
+        end
+        result.sort.to_h
+      end
+    end
+  end
+end

data/lib/ibex/impact/report.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+require_relative "../ir/serialize"
+
+module Ibex
+  module Impact
+    # Builds the deterministic public impact-v1 document.
+    class Report
+      # @rbs @mode: String
+      # @rbs @algorithm: String
+      # @rbs @grammar: IR::Grammar
+      # @rbs @before: IR::Automaton?
+      # @rbs @after: IR::Automaton?
+      # @rbs @seeds: Array[Hash[Symbol, Object?]]
+      # @rbs @nodes: Hash[Integer, Node]
+      # @rbs @symbol_kinds: Hash[Integer, Array[String]]
+      # @rbs @set_changes: Hash[String, Hash[Symbol, Object?]]
+      # @rbs @metadata_names: Array[String]
+      # @rbs @automaton: Hash[Symbol, Object?]
+      # @rbs @actions: Array[Hash[Symbol, Object?]]
+      # @rbs @coverage: Hash[Symbol, Object?]
+      # @rbs @minimum: String
+      # @rbs @warnings: Array[String]
+      # @rbs (mode: String, algorithm: String, grammar: IR::Grammar, before: IR::Automaton?, after: IR::Automaton?,
+      #   seeds: Array[Hash[Symbol, Object?]], nodes: Hash[Integer, Node], symbol_kinds: Hash[Integer, Array[String]],
+      #   set_changes: Hash[String, Hash[Symbol, Object?]], automaton: Hash[Symbol, Object?],
+      #   actions: Array[Hash[Symbol, Object?]], coverage: Hash[Symbol, Object?], ?metadata_names: Array[String],
+      #   ?minimum: String,
+      #   ?warnings: Array[String]) -> void
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(mode:, algorithm:, grammar:, before:, after:, seeds:, nodes:, symbol_kinds:, set_changes:,
+                     automaton:,
+                     actions:, coverage:, metadata_names: [], minimum: "info", warnings: [])
+        @mode = mode
+        @algorithm = algorithm
+        @grammar = grammar
+        @before = before
+        @after = after
+        @seeds = seeds
+        @nodes = nodes
+        @symbol_kinds = symbol_kinds
+        @set_changes = set_changes
+        @metadata_names = metadata_names.uniq.sort
+        @automaton = automaton #: Hash[Symbol, Object?]
+        @actions = actions #: Array[Hash[Symbol, Object?]]
+        @coverage = coverage #: Hash[Symbol, Object?]
+        @minimum = minimum
+        @warnings = warnings
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # @rbs (?minimum: String) -> Hash[Symbol, Object?]
+      def to_h(minimum: @minimum)
+        symbols = symbol_documents(minimum)
+        action_records = action_documents(minimum)
+        {
+          ibex_report: "impact", schema_version: 1, mode: @mode, algorithm: @algorithm,
+          grammar_digest: { before: stable_grammar_digest(@before), after: stable_grammar_digest(@after) },
+          seeds: @seeds.map { |seed| seed.slice(:symbol, :origin, :nullable_boundary) },
+          symbols: symbols, automaton: @automaton, actions: action_records,
+          coverage: coverage_document, warnings: stable_warnings,
+          totals: totals(symbols, action_records, @automaton)
+        }
+      end
+
+      private
+
+      # @rbs (String minimum) -> Array[Hash[Symbol, Object?]]
+      def symbol_documents(minimum)
+        names = (@nodes.keys.filter_map { |id| @grammar.symbol_by_id(id)&.name } + @set_changes.keys + @metadata_names)
+                .uniq.sort
+        documents = names.filter_map { |name| symbol_document(name) }
+        documents.select { |document| Severity::RANK.fetch(severity_of(document)) >= Severity::RANK.fetch(minimum) }
+      end
+
+      # @rbs (String) -> Hash[Symbol, Object?]?
+      def symbol_document(name)
+        id = @grammar.symbol(name)&.id
+        node = id && @nodes[id]
+        return unless reportable_symbol?(name)
+
+        kinds = symbol_kinds_for(name, id)
+        kinds = ["reference"] if kinds.empty? && node
+        severity = document_severity(name, kinds)
+        {
+          symbol: name, severity: severity, kinds: kinds, distance: node&.distance || 0,
+          component: component_names(node, name),
+          sets: @set_changes.fetch(name, { first: empty_change, follow: empty_change, nullable: nil }),
+          witness: witness_documents(node&.witness || [])
+        }
+      end
+
+      # @rbs (String) -> bool
+      def reportable_symbol?(name)
+        !!(@grammar.symbol(name) || @set_changes.key?(name) || @metadata_names.include?(name))
+      end
+
+      # @rbs (String, Integer?) -> Array[String]
+      def symbol_kinds_for(name, id)
+        kinds = id ? (@symbol_kinds[id] || []).dup : [] #: Array[String]
+        kinds << "metadata" if @metadata_names.include?(name)
+        kinds.concat(change_kinds(name))
+        kinds.uniq.sort
+      end
+
+      # @rbs (String) -> Array[String]
+      def change_kinds(name)
+        change = @set_changes[name]
+        return [] unless change
+
+        kinds = [] #: Array[String]
+        first = change.fetch(:first, empty_change)
+        follow = change.fetch(:follow, empty_change)
+        kinds << "first" unless first.fetch(:added).empty? && first.fetch(:removed).empty?
+        kinds << "follow" unless follow.fetch(:added).empty? && follow.fetch(:removed).empty?
+        kinds << "nullable" if change.fetch(:nullable, nil)
+        kinds
+      end
+
+      # @rbs (String, Array[String]) -> String
+      def document_severity(name, kinds)
+        level = kinds.reduce("info") { |current, kind| Severity.max(current, kind_severity(kind)) }
+        action_severity(name, level)
+      end
+
+      # @rbs (Node?, String) -> Array[String]
+      def component_names(node, name)
+        return [name] unless node
+
+        node.component.sort.map { |member| @grammar.symbol_by_id(member)&.name }.compact.sort
+      end
+
+      # @rbs (String kind) -> String
+      def kind_severity(kind)
+        return "high" if %w[first follow nullable action_arity].include?(kind)
+        return "medium" if %w[reference precedence].include?(kind)
+        return "low" if kind == "metadata"
+
+        "info"
+      end
+
+      # @rbs (String name, String current) -> String
+      def action_severity(name, current)
+        findings = @actions.select { |action| action_production(action).start_with?("#{name} ->") }
+        findings.reduce(current) { |level, finding| Severity.max(level, severity_of(finding)) }
+      end
+
+      # @rbs (Hash[Symbol, Object?] record) -> String
+      def severity_of(record)
+        record.fetch(:severity) #: String
+      end
+
+      # @rbs () -> Hash[Symbol, Array[String]]
+      def empty_change
+        { added: [], removed: [] }
+      end
+
+      # @rbs (Array[Edge]) -> Array[Hash[Symbol, Object?]]
+      def witness_documents(witness)
+        witness.map do |edge|
+          production = edge.production && @grammar.productions[edge.production]
+          location = production&.origin&.fetch(:loc, nil) #: IR::location?
+          {
+            from: symbol_name(edge.source), to: symbol_name(edge.target), production: production_shape(production),
+            loc: stable_location(location)
+          }
+        end
+      end
+
+      # @rbs (Integer) -> String
+      def symbol_name(id)
+        @grammar.symbol_by_id(id)&.name || id.to_s
+      end
+
+      # @rbs (IR::Production?) -> String?
+      def production_shape(production)
+        return unless production
+
+        lhs = symbol_name(production.lhs)
+        rhs = production.rhs.map { |id| symbol_name(id) }
+        "#{lhs} -> #{rhs.join(' ')}"
+      end
+
+      # @rbs (Array[Hash[Symbol, Object?]], Array[Hash[Symbol, Object?]],
+      #   Hash[Symbol, Object?]) -> Hash[Symbol, Integer]
+      def totals(symbols, actions, automaton)
+        counts = Severity::LEVELS.to_h { |level| [level.to_sym, 0] }
+        symbols.each { |item| counts[item.fetch(:severity).to_s.to_sym] += 1 }
+        actions.each { |item| counts[item.fetch(:severity).to_s.to_sym] += 1 }
+        conflicts = automaton.dig(:conflicts, :added) || [] #: Array[Hash[Symbol, Object?]]
+        counts[:critical] += conflicts.length
+        unreachable = automaton.fetch(:unreachable, []) #: Array[Integer]
+        counts[:critical] += unreachable.length
+        unreachable_nonterminals = automaton.fetch(:unreachable_nonterminals, []) #: Array[String]
+        counts[:critical] += unreachable_nonterminals.length
+        counts
+      end
+
+      # @rbs (String minimum) -> Array[Hash[Symbol, Object?]]
+      def action_documents(minimum)
+        documents = @actions.sort_by { |action| action_production(action) }.map do |action|
+          production = action_production(action)
+          severity = action.fetch(:severity) #: String
+          reason = action.fetch(:reason) #: String
+          context_length = action.fetch(:context_length) #: Hash[Symbol, Integer]
+          location = action.fetch(:loc, nil) #: IR::location?
+          {
+            production: production, severity: severity, reason: reason,
+            context_length: context_length, loc: stable_location(location)
+          }
+        end
+        documents.select { |action| Severity::RANK.fetch(severity_of(action)) >= Severity::RANK.fetch(minimum) }
+      end
+
+      # @rbs (Hash[Symbol, Object?] action) -> String
+      def action_production(action)
+        action.fetch(:production) #: String
+      end
+
+      # @rbs () -> Hash[Symbol, Object?]
+      def coverage_document
+        empty_reports = [] #: Array[Hash[Symbol, Object?]]
+        reports = @coverage.fetch(:reports, empty_reports) #: Array[Hash[Symbol, Object?]]
+        status = @coverage.fetch(:status) #: String
+        { status: status,
+          reports: reports.sort_by { |report| coverage_report_path(report) }.map do |report|
+            productions = report.fetch(:productions) #: Array[Integer]
+            { path: stable_path(coverage_report_path(report)), productions: productions.sort }
+          end }
+      end
+
+      # @rbs (Hash[Symbol, Object?] report) -> String
+      def coverage_report_path(report)
+        report.fetch(:path) #: String
+      end
+
+      # @rbs () -> Array[String]
+      def stable_warnings
+        empty_reports = [] #: Array[Hash[Symbol, Object?]]
+        paths = @coverage.fetch(:reports, empty_reports).map { |report| coverage_report_path(report) }
+        @warnings.map do |warning|
+          paths.reduce(warning) { |current, path| current.gsub(path, stable_path(path)) }
+        end.sort.uniq
+      end
+
+      # @rbs (IR::location?) -> Hash[Symbol, Integer]?
+      def stable_location(location)
+        return unless location
+
+        { line: location[:line], column: location[:column] }
+      end
+
+      # @rbs (IR::Automaton?) -> String?
+      def stable_grammar_digest(automaton)
+        return unless automaton
+
+        serialized = IR::Serialize.dump(automaton.grammar)
+        canonical = serialized.gsub(/"file":\s*"[^"]*"/, '"file": "<source>"')
+        canonical = canonical.gsub(/"root":\s*"[^"]*"/, '"root": null')
+        "sha256:#{Digest::SHA256.hexdigest(canonical)}"
+      end
+
+      # @rbs (String) -> String
+      def stable_path(path)
+        return path unless path.start_with?(File::SEPARATOR)
+
+        File.basename(path)
+      end
+    end
+  end
+end