ibex 0.1.0 → 0.3.0

data/lib/ibex/error_messages/parser_v2.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Ibex
+  module ErrorMessages
+    # Sentence-keyed ibex-messages v2 parsing, mixed into Parser so both
+    # versions share UTF-8, escape, and positioned-diagnostic helpers.
+    module ParserV2
+      # @rbs!
+      #   private def ignorable?: (String) -> bool
+      #   private def column: (String) -> Integer
+      #   private def fail_at: (Integer, Integer, String) -> bot
+      #   private def decode_line: (String, Integer, Integer) -> String
+
+      private
+
+      # @rbs () -> Document
+      def parse_v2
+        entries = [] #: Array[Entry]
+        identifiers = {} #: Hash[String, Integer]
+        keys = {} #: Hash[String, Integer]
+        index = 1
+        while index < @lines.length
+          line = @lines.fetch(index)
+          if ignorable?(line) && !line.lstrip.start_with?("##")
+            index += 1
+            next
+          end
+
+          entry, index = parse_v2_entry(index)
+          record_v2_entry(entry, entries, identifiers, keys)
+        end
+        Document.new(version: 2, entries: entries)
+      end
+
+      # @rbs (Entry entry, Array[Entry] entries, Hash[String, Integer] identifiers,
+      #   Hash[String, Integer] keys) -> void
+      def record_v2_entry(entry, entries, identifiers, keys)
+        error_id = entry.error_id || raise(Ibex::Error, "missing error id")
+        reject_v2_duplicate(identifiers, error_id, entry.line, "error id")
+        key = entry.sentence ? "#{entry.entry}\0#{entry.sentence.join("\0")}" : "legacy\0#{entry.state}"
+        reject_v2_duplicate(keys, key, entry.line, "sentence")
+        identifiers[error_id] = entry.line
+        keys[key] = entry.line
+        entries << entry
+      end
+
+      # @rbs (Integer opening_index) -> [Entry, Integer]
+      def parse_v2_entry(opening_index)
+        status, sentence, state = parse_v2_opening(opening_index)
+        read_v2_entry_body(opening_index, status, sentence, state)
+      end
+
+      # @rbs (Integer opening_index) ->
+      #   [:active | :unreachable | :removed, Array[String]?, Integer?]
+      def parse_v2_opening(opening_index)
+        opening = @lines.fetch(opening_index)
+        if (legacy = opening.match(/\Alegacy-state:[ \t]*([0-9]+)\z/))
+          return [:removed, nil, Integer(legacy[1] || "0", 10)]
+        end
+
+        if (sentence = opening.match(/\A(sentence|unreachable):[ \t]*(.*)\z/))
+          status = sentence[1] == "unreachable" ? :unreachable : :active #: :unreachable | :active
+          return [status, parse_sentence(sentence[2] || "", opening_index + 1), nil]
+        end
+
+        fail_at(opening_index + 1, column(opening),
+                "expected `sentence: TOKENS`, `unreachable: TOKENS`, or `legacy-state: N`")
+      end
+
+      # @rbs (Integer opening_index, :active | :unreachable | :removed status, Array[String]? sentence,
+      #   Integer? state) -> [Entry, Integer]
+      def read_v2_entry_body(opening_index, status, sentence, state)
+        error_id = nil #: String?
+        entry_name = nil #: String?
+        message_lines = [] #: Array[String]
+        index = opening_index + 1
+        while index < @lines.length
+          line = @lines.fetch(index)
+          if line.strip == "end"
+            return close_v2_entry(
+              opening_index, index, status, sentence, state, error_id, entry_name, message_lines
+            )
+          end
+
+          error_id, state, entry_name = read_v2_metadata(
+            line, index, error_id, state, entry_name, message_lines
+          )
+          index += 1
+        end
+        fail_at(opening_index + 1, 1, "unterminated error-sentence entry")
+      end
+
+      # @rbs (Integer opening_index, Integer index, :active | :unreachable | :removed status,
+      #   Array[String]? sentence, Integer? state, String? error_id, String? entry_name,
+      #   Array[String] message_lines) -> [Entry, Integer]
+      def close_v2_entry(opening_index, index, status, sentence, state, error_id, entry_name, message_lines)
+        fail_at(opening_index + 1, 1, "missing `## E0001` error id") unless error_id
+        message = message_lines.empty? ? nil : message_lines.join("\n")
+        fail_at(opening_index + 1, 1, "message must not be empty") if message&.strip&.empty?
+        entry = Entry.new(
+          state: state, status: status, message: message, line: opening_index + 1,
+          sentence: sentence, error_id: error_id, entry: entry_name
+        )
+        [entry, index + 1]
+      end
+
+      # @rbs (String line, Integer index, String? error_id, Integer? state, String? entry_name,
+      #   Array[String] message_lines) -> [String?, Integer?, String?]
+      def read_v2_metadata(line, index, error_id, state, entry_name, message_lines)
+        stripped = line.strip
+        if (match = stripped.match(/\A##[ \t]+(E[0-9]{4,})\z/))
+          fail_at(index + 1, column(line), "duplicate error id") if error_id
+          error_id = match[1]
+        elsif (match = stripped.match(/\A# state:[ \t]*([0-9]+)\z/))
+          state = Integer(match[1] || "0", 10)
+        elsif (match = stripped.match(/\A# entry:[ \t]*(\S+)\z/))
+          entry_name = match[1]
+        elsif line.start_with?("|")
+          append_v2_message_line(message_lines, line, index)
+        elsif !ignorable?(line)
+          fail_at(index + 1, column(line), "expected metadata, a `| ` message line, a comment, or `end`")
+        end
+        [error_id, state, entry_name]
+      end
+
+      # @rbs (Array[String] message_lines, String line, Integer index) -> void
+      def append_v2_message_line(message_lines, line, index)
+        content = line.delete_prefix("|").delete_prefix(" ")
+        content_column = line.start_with?("| ") ? 3 : 2
+        message_lines << decode_line(content, index + 1, content_column)
+      end
+
+      # @rbs (String source, Integer line) -> Array[String]
+      def parse_sentence(source, line)
+        tokens = [] #: Array[String]
+        index = 0
+        loop do
+          index = skip_sentence_space(source, index)
+          break if index == source.length
+
+          token, index = read_sentence_token(source, index, line)
+          tokens << token
+        end
+        fail_at(line, 1, "error sentence must contain at least one token") if tokens.empty?
+        tokens
+      end
+
+      # @rbs (String source, Integer index) -> Integer
+      def skip_sentence_space(source, index)
+        index += 1 while index < source.length && source[index]&.match?(/\s/)
+        index
+      end
+
+      # @rbs (String source, Integer index, Integer line) -> [String, Integer]
+      def read_sentence_token(source, index, line)
+        start = index
+        quote = source[index]
+        if ["'", '"'].include?(quote)
+          index = quoted_token_end(source, index, quote || "", line)
+        else
+          index += 1 while index < source.length && !source[index]&.match?(/\s/)
+        end
+        token = source[start...index] || raise(Ibex::Error, "missing sentence token")
+        [token, index]
+      end
+
+      # @rbs (String source, Integer index, String quote, Integer line) -> Integer
+      def quoted_token_end(source, index, quote, line)
+        ending = scan_quoted_token(source, index, quote, line)
+        return ending if ending == source.length || source[ending]&.match?(/\s/)
+
+        fail_at(line, ending + 1, "quoted token must be followed by whitespace")
+      end
+
+      # @rbs (String source, Integer index, String quote, Integer line) -> Integer
+      def scan_quoted_token(source, index, quote, line)
+        index += 1
+        while index < source.length
+          character = source[index]
+          if character == "\\"
+            index += 2
+          elsif character == quote
+            return index + 1
+          else
+            index += 1
+          end
+        end
+        fail_at(line, source.length + 1, "unterminated quoted token")
+      end
+
+      # @rbs (Hash[String, Integer] declarations, String key, Integer line, String label) -> void
+      def reject_v2_duplicate(declarations, key, line, label)
+        previous = declarations[key]
+        fail_at(line, 1, "duplicate #{label}; first declared at line #{previous}") if previous
+      end
+    end
+  end
+end

data/lib/ibex/error_messages/renderer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Ibex
+  module ErrorMessages
+    # @rbs (IR::Automaton automaton, Array[Entry] entries) -> String
+    def render_entries(automaton, entries)
+      lines = [
+        HEADER,
+        "# Generated by `ibex errors --update`; sentences and IDs are stable review keys.",
+        "# Edit only `| ` message lines.",
+        ""
+      ]
+      entries.each { |entry| append_entry(lines, automaton, entry) }
+      "#{lines.join("\n").rstrip}\n"
+    end
+
+    # @rbs (Array[String] lines, IR::Automaton automaton, Entry entry) -> void
+    def append_entry(lines, automaton, entry)
+      lines << entry_heading(entry)
+      lines << "## #{entry.error_id}"
+      lines << "# entry: #{entry.entry}" if entry.entry
+      lines << "# state: #{entry.state}" if entry.state
+      append_expected_tokens(lines, automaton, entry)
+      lines << "# Add one or more `| ` lines to customize this error." unless entry.message
+      entry.message&.split("\n", -1)&.each { |line| lines << "| #{encode_line(line)}" }
+      lines.push("end", "")
+    end
+
+    # @rbs (Entry entry) -> String
+    def entry_heading(entry)
+      return "legacy-state: #{entry.state}" unless entry.sentence
+
+      prefix = entry.status == :active ? "sentence" : "unreachable"
+      "#{prefix}: #{entry.sentence.join(' ')}"
+    end
+
+    # @rbs (Array[String] lines, IR::Automaton automaton, Entry entry) -> void
+    def append_expected_tokens(lines, automaton, entry)
+      return unless entry.status == :active && entry.state
+
+      expected = expected_tokens(automaton, automaton.states.fetch(entry.state))
+      lines << "# expected: #{expected.empty? ? '(none)' : expected.join(', ')}"
+    end
+
+    # @rbs (String line) -> String
+    def encode_line(line)
+      line.gsub("\\", "\\\\").gsub("\t", "\\t").gsub("\r", "\\r")
+    end
+
+    # @rbs (IR::Automaton automaton, IR::AutomatonState state) -> Array[String]
+    def expected_tokens(automaton, state)
+      ordinary_terminals(automaton).filter_map do |terminal|
+        action = state.actions[terminal.id] || state.default_action
+        terminal.display_name || terminal.name unless error_action?(action)
+      end
+    end
+
+    module_function :render_entries, :append_entry, :entry_heading, :append_expected_tokens, :encode_line,
+                    :expected_tokens
+
+    class << self
+      private :render_entries, :append_entry, :entry_heading, :append_expected_tokens, :encode_line, :expected_tokens
+    end
+  end
+end

data/lib/ibex/error_messages/sentence_search.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative "../lalr/conflict_search_limits"
+
+module Ibex
+  module ErrorMessages
+    # Finds deterministic shortest token sentences that reach each syntax
+    # error state without running semantic actions.
+    class SentenceSearch
+      DEFAULT_MAX_TOKENS = LALR::ConflictSearchLimits::DEFAULT_MAX_TOKENS #: Integer
+      DEFAULT_MAX_CONFIGURATIONS = LALR::ConflictSearchLimits::DEFAULT_MAX_CONFIGURATIONS #: Integer
+
+      Witness = Struct.new(
+        :entry, #: String
+        :tokens, #: Array[String]
+        :state, #: Integer
+        keyword_init: true
+      )
+
+      # @rbs @automaton: IR::Automaton
+      # @rbs @grammar: IR::Grammar
+      # @rbs @max_tokens: Integer
+      # @rbs @max_configurations: Integer
+      # @rbs @candidates: Array[IR::GrammarSymbol]
+      # @rbs @input_candidates: Array[IR::GrammarSymbol]
+      # @rbs @explored: Integer
+
+      # @rbs (IR::Automaton automaton, ?max_tokens: Integer, ?max_configurations: Integer) -> void
+      def initialize(automaton, max_tokens: DEFAULT_MAX_TOKENS,
+                     max_configurations: DEFAULT_MAX_CONFIGURATIONS)
+        LALR::ConflictSearchLimits.validate!(
+          max_tokens: max_tokens, max_configurations: max_configurations
+        )
+        @automaton = automaton
+        @grammar = automaton.grammar
+        @max_tokens = max_tokens
+        @max_configurations = max_configurations
+        @candidates = grammar_terminals
+        @input_candidates = @candidates.reject { |symbol| symbol.id.zero? }
+        @explored = 0
+      end
+
+      # @rbs () -> Hash[Integer, Witness]
+      def all
+        targets = ErrorMessages.error_states(@automaton).to_h { |state| [state.id, true] }
+        witnesses = {} #: Hash[Integer, Witness]
+        @automaton.entry_states.each do |entry, initial_state|
+          search_entry(entry, initial_state, targets, witnesses)
+          break if witnesses.length == targets.length
+        end
+        witnesses.sort.to_h.freeze
+      end
+
+      # @rbs (Array[String] tokens, ?entry: String?) -> Integer?
+      def state_for(tokens, entry: nil)
+        return nil if tokens.empty?
+
+        start = entry || @grammar.start
+        initial = @automaton.entry_states[start]
+        return nil unless initial
+
+        states = [initial]
+        tokens.each_with_index do |name, index|
+          status, value = consume_sentence_token(states, name, index == tokens.length - 1)
+          return value if status == :error && value.is_a?(Integer)
+          return nil unless status == :continue && value.is_a?(Array)
+
+          states = value
+        end
+        nil
+      end
+
+      private
+
+      # @rbs (Array[Integer] states, String name, bool final) ->
+      #   [Symbol, Array[Integer] | Integer | nil]
+      def consume_sentence_token(states, name, final)
+        symbol = sentence_symbol(name, final)
+        return [:invalid, nil] unless symbol
+
+        status, value = advance(states, symbol.id)
+        return [:error, value] if status == :error && final && value.is_a?(Integer)
+        return [:continue, value] if status == :shift && value.is_a?(Array)
+
+        [:invalid, nil]
+      end
+
+      # @rbs (String name, bool final) -> IR::GrammarSymbol?
+      def sentence_symbol(name, final)
+        symbol = @grammar.symbol(name)
+        return nil unless symbol&.terminal?
+        return nil if symbol.name == "error" || (symbol.id.zero? && !final)
+
+        symbol
+      end
+
+      # @rbs () -> Array[IR::GrammarSymbol]
+      def grammar_terminals
+        @grammar.terminals
+                .reject { |symbol| symbol.name == "error" }
+                .sort_by { |symbol| [symbol.id.zero? ? 1 : 0, symbol.name] }
+      end
+
+      # @rbs (String entry, Integer initial_state, Hash[Integer, bool] targets,
+      #   Hash[Integer, Witness] witnesses) -> void
+      def search_entry(entry, initial_state, targets, witnesses)
+        queue = [[[initial_state], Array.new(0)]] #: Array[[Array[Integer], Array[String]]]
+        visited = { [initial_state] => true }
+        until queue.empty? || witnesses.length == targets.length
+          states, prefix = queue.shift
+          count_configuration!
+          collect_errors(entry, states, prefix, targets, witnesses)
+          enqueue_shifts(queue, visited, states, prefix) if prefix.length < @max_tokens - 1
+        end
+      end
+
+      # @rbs (String entry, Array[Integer] states, Array[String] prefix, Hash[Integer, bool] targets,
+      #   Hash[Integer, Witness] witnesses) -> void
+      def collect_errors(entry, states, prefix, targets, witnesses)
+        @candidates.each do |symbol|
+          status, state = advance(states, symbol.id)
+          next unless status == :error && state.is_a?(Integer)
+
+          error_state = state #: Integer
+          next unless targets[error_state] && !witnesses[error_state]
+
+          witnesses[error_state] = Witness.new(
+            entry: entry, tokens: (prefix + [symbol.name]).freeze, state: error_state
+          ).freeze
+        end
+      end
+
+      # @rbs (Array[[Array[Integer], Array[String]]] queue, Hash[Array[Integer], bool] visited,
+      #   Array[Integer] states, Array[String] prefix) -> void
+      def enqueue_shifts(queue, visited, states, prefix)
+        @input_candidates.each do |symbol|
+          status, shifted = advance(states, symbol.id)
+          next unless status == :shift && shifted.is_a?(Array)
+
+          shifted_states = shifted #: Array[Integer]
+          next if visited[shifted_states]
+
+          visited[shifted_states] = true
+          queue << [shifted_states, prefix + [symbol.name]]
+        end
+      end
+
+      # @rbs (Array[Integer] initial, Integer token_id) -> [Symbol, Array[Integer] | Integer | nil]
+      def advance(initial, token_id)
+        states = initial
+        visited = {} #: Hash[Array[Integer], bool]
+        loop do
+          return [:invalid, nil] if visited[states]
+
+          visited[states] = true
+          state = @automaton.states.fetch(states.last)
+          action = state.actions[token_id] || state.default_action
+          return [:error, state.id] if action.nil? || action[:type] == :error
+
+          case action[:type]
+          when :shift
+            shift = action #: IR::shift_action
+            return [:shift, (states + [shift[:state]]).freeze]
+          when :reduce
+            reduce = action #: IR::reduce_action
+            states = reduce_stack(states, reduce[:production])
+            return [:invalid, nil] unless states
+          when :accept
+            return [:accept, nil]
+          else
+            return [:invalid, nil]
+          end
+        end
+      end
+
+      # @rbs (Array[Integer] states, Integer production_id) -> Array[Integer]?
+      def reduce_stack(states, production_id)
+        production = @grammar.productions.fetch(production_id)
+        return nil if production.rhs.length >= states.length
+
+        remaining = states.take(states.length - production.rhs.length)
+        target = @automaton.states.fetch(remaining.last).gotos[production.lhs]
+        target && (remaining + [target]).freeze
+      end
+
+      # @rbs () -> void
+      def count_configuration!
+        @explored += 1
+        return if @explored <= @max_configurations
+
+        raise Ibex::Error,
+              "(messages):1:1: error-sentence search exceeded #{@max_configurations} configurations"
+      end
+    end
+  end
+end

data/lib/ibex/error_messages/update.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "renderer"
+
+module Ibex
+  module ErrorMessages
+    # @rbs (IR::Automaton automaton, ?existing: Document?, ?max_tokens: Integer,
+    #   ?max_configurations: Integer) -> String
+    def render(automaton, existing: nil, max_tokens: SentenceSearch::DEFAULT_MAX_TOKENS,
+               max_configurations: SentenceSearch::DEFAULT_MAX_CONFIGURATIONS)
+      update(
+        automaton, existing: existing, max_tokens: max_tokens, max_configurations: max_configurations
+      ).source
+    end
+    module_function :render
+
+    # @rbs (IR::Automaton automaton, ?existing: Document?, ?max_tokens: Integer,
+    #   ?max_configurations: Integer) -> Update
+    def update(automaton, existing: nil, max_tokens: SentenceSearch::DEFAULT_MAX_TOKENS,
+               max_configurations: SentenceSearch::DEFAULT_MAX_CONFIGURATIONS)
+      document = existing || Document.new(entries: [])
+      search = SentenceSearch.new(
+        automaton, max_tokens: max_tokens, max_configurations: max_configurations
+      )
+      witnesses = search.all
+      classifications = { uncovered: [], unreachable: [], moved: [] } #: Hash[Symbol, Array[String]]
+      next_id = next_error_id(document)
+      entries, covered, next_id = update_existing_entries(
+        document, search, witnesses, classifications, next_id
+      )
+      add_uncovered_entries(entries, covered, witnesses, classifications[:uncovered], next_id)
+      entries.sort_by! { |entry| entry_sort_key(entry) }
+      Update.new(
+        source: render_entries(automaton, entries),
+        uncovered: classifications[:uncovered],
+        unreachable: classifications[:unreachable],
+        moved: classifications[:moved]
+      )
+    end
+    module_function :update
+
+    # @rbs (Array[Entry] entries, Hash[Integer, bool] covered,
+    #   Hash[Integer, SentenceSearch::Witness] witnesses, Array[String] uncovered, Integer next_id) -> void
+    def add_uncovered_entries(entries, covered, witnesses, uncovered, next_id)
+      witnesses.each do |state, witness|
+        next if covered[state]
+
+        error_id = format_error_id(next_id)
+        next_id += 1
+        entries << Entry.new(
+          state: state, status: :active, message: nil, line: 1,
+          sentence: witness.tokens, error_id: error_id, entry: witness.entry
+        )
+        uncovered << "#{error_id} state #{state}: #{witness.tokens.join(' ')}"
+      end
+    end
+
+    # @rbs (Document document, SentenceSearch search, Hash[Integer, SentenceSearch::Witness] witnesses,
+    #   Hash[Symbol, Array[String]] classifications, Integer next_id) ->
+    #   [Array[Entry], Hash[Integer, bool], Integer]
+    def update_existing_entries(document, search, witnesses, classifications, next_id)
+      return migrate_legacy_entries(document, witnesses, classifications, next_id) if document.version == 1
+
+      entries = [] #: Array[Entry]
+      covered = {} #: Hash[Integer, bool]
+      document.entries.each do |entry|
+        if entry.sentence
+          next_id = update_sentence_entry(
+            entry, search, entries, covered, classifications, next_id
+          )
+        else
+          entries << with_error_id(entry, next_id)
+          next_id += 1 unless entry.error_id
+        end
+      end
+      [entries, covered, next_id]
+    end
+
+    # @rbs (Entry entry, SentenceSearch search, Array[Entry] entries, Hash[Integer, bool] covered,
+    #   Hash[Symbol, Array[String]] classifications, Integer next_id) -> Integer
+    def update_sentence_entry(entry, search, entries, covered, classifications, next_id)
+      error_id = entry.error_id || format_error_id(next_id)
+      next_id += 1 unless entry.error_id
+      sentence = entry.sentence || raise(Ibex::Error, "missing error sentence")
+      state = search.state_for(sentence, entry: entry.entry)
+      unless state
+        entries << Entry.new(
+          state: entry.state, status: :unreachable, message: entry.message, line: entry.line,
+          sentence: sentence, error_id: error_id, entry: entry.entry
+        )
+        classifications[:unreachable] << "#{error_id}: #{sentence.join(' ')}"
+        return next_id
+      end
+
+      classifications[:moved] << "#{error_id}: state #{entry.state} -> #{state}" if entry.state && entry.state != state
+      covered[state] = true
+      entries << Entry.new(
+        state: state, status: :active, message: entry.message, line: entry.line,
+        sentence: sentence, error_id: error_id, entry: entry.entry
+      )
+      next_id
+    end
+
+    # @rbs (Document document, Hash[Integer, SentenceSearch::Witness] witnesses,
+    #   Hash[Symbol, Array[String]] classifications, Integer next_id) ->
+    #   [Array[Entry], Hash[Integer, bool], Integer]
+    def migrate_legacy_entries(document, witnesses, classifications, next_id)
+      by_state = document.entries.to_h { |entry| [entry.state, entry] }
+      entries = [] #: Array[Entry]
+      covered = {} #: Hash[Integer, bool]
+      witnesses.each do |state, witness|
+        previous = by_state.delete(state)
+        error_id = format_error_id(next_id)
+        next_id += 1
+        entries << Entry.new(
+          state: state, status: :active, message: previous&.message, line: previous&.line || 1,
+          sentence: witness.tokens, error_id: error_id, entry: witness.entry
+        )
+        covered[state] = true
+        classifications[:uncovered] << "#{error_id} state #{state}: #{witness.tokens.join(' ')}" unless previous
+      end
+      by_state.values.sort_by { |entry| entry.state || -1 }.each do |entry|
+        error_id = format_error_id(next_id)
+        next_id += 1
+        entries << Entry.new(
+          state: entry.state, status: :removed, message: entry.message, line: entry.line, error_id: error_id
+        )
+        classifications[:unreachable] << "#{error_id}: legacy state #{entry.state}"
+      end
+      [entries, covered, next_id]
+    end
+
+    # @rbs (Entry entry, Integer next_id) -> Entry
+    def with_error_id(entry, next_id)
+      Entry.new(
+        state: entry.state, status: entry.status, message: entry.message, line: entry.line,
+        sentence: entry.sentence, error_id: entry.error_id || format_error_id(next_id), entry: entry.entry
+      )
+    end
+
+    # @rbs (Document document) -> Integer
+    def next_error_id(document)
+      maximum = document.entries.filter_map do |entry|
+        match = entry.error_id&.match(/\AE([0-9]{4,})\z/)
+        match && Integer(match[1] || "0", 10)
+      end.max
+      (maximum || 0) + 1
+    end
+
+    # @rbs (Integer number) -> String
+    def format_error_id(number)
+      format("E%04d", number)
+    end
+
+    # @rbs (Entry entry) -> [Integer, Integer, String]
+    def entry_sort_key(entry)
+      rank = { active: 0, unreachable: 1, removed: 2 }.fetch(entry.status)
+      [rank, entry.state || (1 << 62), entry.error_id || ""]
+    end
+
+    module_function :add_uncovered_entries, :update_existing_entries, :update_sentence_entry, :migrate_legacy_entries,
+                    :with_error_id, :next_error_id, :format_error_id, :entry_sort_key
+
+    class << self
+      private :add_uncovered_entries, :update_existing_entries, :update_sentence_entry, :migrate_legacy_entries,
+              :with_error_id, :next_error_id, :format_error_id, :entry_sort_key
+    end
+  end
+end