pubid 2.0.0.pre.alpha.2 → 2.0.0.pre.alpha.3

data/lib/pubid/nist/parser_output_normalizer.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Nist
+    # Normalizes the raw hash produced by the NIST parser before the Builder
+    # constructs the identifier object.
+    #
+    # The parser emits a flat hash with keys like :first_number, :second_number,
+    # :edition_dash_year, :update_prefix, etc. Many of those keys are
+    # *incompatible shapes* — e.g. parser captures a year as :edition_dash_year
+    # when it is actually a second_number, or a letter+digits suffix lives
+    # inside :first_number when it should become a Part component.
+    #
+    # Each `normalize_*` method here performs one such shape correction,
+    # mutating the hash in place. The Normalizer is intentionally
+    # *side-effect-only*: it never reads from the Builder, the Caster, or the
+    # identifier classes, so it can be tested in isolation.
+    #
+    # Pre-processing blocks that need to surface extracted components to the
+    # Builder (e.g. letter-suffix Part components, embedded-edition objects)
+    # remain in Builder#build because they create local variables that flow
+    # into the construction phase. All other normalizations live here.
+    class ParserOutputNormalizer
+      # Range of years we treat as "looks like a calendar year" when
+      # disambiguating :edition_dash_year from :second_number.
+      VALID_YEAR_RANGE = (1901..2026).freeze
+
+      # Series that treat :edition_dash_year as a year-only edition when the
+      # dash year falls in VALID_YEAR_RANGE. For other series with a dash-year
+      # in this range, the dash-year is interpreted differently (or kept as
+      # a compound number, depending on the branch).
+      DASH_YEAR_AS_EDITION_SERIES = %w[HB CS FIPS].freeze
+
+      # Apply all normalizations to the parsed hash in the correct order.
+      # @param parsed_hash [Hash] parser output (mutated in place)
+      # @return [Hash] the same hash, normalized
+      def normalize(parsed_hash)
+        merge_edition_e_into_update(parsed_hash)
+        extract_embedded_edition_with_year(parsed_hash)
+        extract_embedded_edition_without_dash_year(parsed_hash)
+        split_second_number_edition_year(parsed_hash)
+        split_fips_month_year_after_part(parsed_hash)
+        disambiguate_ir_compound_vs_edition(parsed_hash)
+        disambiguate_dash_year(parsed_hash)
+        parsed_hash
+      end
+
+      private
+
+      # Pattern: "800-53r4/Upd3-2015"
+      # Parser captures "-2015" as :edition_e but it belongs on :update.
+      def merge_edition_e_into_update(parsed_hash)
+        return unless parsed_hash[:update_prefix] && parsed_hash[:update] && parsed_hash[:edition_e]
+
+        edition_id = parsed_hash[:edition_e][:edition_id]
+        parsed_hash[:update] = parsed_hash[:update].merge(update_year: edition_id)
+        parsed_hash.delete(:edition_e)
+      end
+
+      # Pattern: "44e2-1955"
+      # first_number="44e2", edition_dash_year="1955"
+      # Result: first_number="44", edition(type:"e", id:"2", additional_text:"1955")
+      def extract_embedded_edition_with_year(parsed_hash)
+        return unless parsed_hash[:first_number]&.to_s&.match?(/^[0-9]+[a-zA-Z]\d+$/) &&
+                      parsed_hash[:edition_dash_year]
+
+        number_str = parsed_hash[:first_number].to_s
+        return unless (match_data = number_str.match(/^(\d+)([a-zA-Z])(\d+)$/))
+
+        base_number, edition_type, edition_id = match_data[1], match_data[2].downcase, match_data[3]
+
+        parsed_hash[:first_number] = Components::Code.new(value: base_number)
+        parsed_hash[:edition_with_year] = Components::Edition.new(
+          type: edition_type,
+          id: edition_id,
+          additional_text: parsed_hash[:edition_dash_year][:dash_year],
+        )
+        parsed_hash.delete(:edition_dash_year)
+      end
+
+      # Pattern: "8115r1" (with no edition_dash_year)
+      # first_number="8115r1", no second_number
+      # Result: first_number="8115", edition(type:"r", id:"1")
+      #
+      # CRITICAL: Only when no :second_number is present, otherwise the
+      # compound-number logic in the Builder handles the pattern.
+      def extract_embedded_edition_without_dash_year(parsed_hash)
+        return if parsed_hash[:second_number]
+        return unless parsed_hash[:first_number]&.to_s&.match?(/^[0-9]+[a-zA-Z]\d+$/)
+        return if parsed_hash[:edition_dash_year]
+
+        number_str = parsed_hash[:first_number].to_s
+        return unless (match_data = number_str.match(/^(\d+)([a-zA-Z])(\d+)$/))
+
+        base_number, edition_type, edition_id = match_data[1], match_data[2].downcase, match_data[3]
+
+        parsed_hash[:first_number] = Components::Code.new(value: base_number)
+        parsed_hash[:edition_with_year] = Components::Edition.new(
+          type: edition_type,
+          id: edition_id,
+        )
+      end
+
+      # Pattern: "105-1-1990"
+      # Parser returns second_number_edition_year={second_number:"1", dash_year:"1990"}
+      # Result: :second_number="1", plus either :edition_from_year (HB series)
+      # or :edition_dash_year (other series) for further downstream processing.
+      def split_second_number_edition_year(parsed_hash)
+        return unless parsed_hash[:second_number_edition_year]
+
+        combined = parsed_hash[:second_number_edition_year]
+        parsed_hash[:second_number] = combined[:second_number]
+        dash_year = combined[:dash_year]
+
+        is_handbook = safely_to_s(parsed_hash[:series]) == "HB"
+        if is_handbook && dash_year.to_s.match?(/^\d{4}$/)
+          parsed_hash[:edition_from_year] = Components::Edition.new(type: "e", id: dash_year)
+        else
+          parsed_hash[:edition_dash_year] = { dash_year: dash_year }
+        end
+
+        parsed_hash.delete(:second_number_edition_year)
+      end
+
+      # Pattern: "11-1-Sep1977"
+      # Parser returns fips_month_year_after_part={second_number:"1", edition_month:"Sep", edition_year:"1977"}
+      # Result: :second_number="1", :edition_from_year(type:"e", id:"197709")
+      def split_fips_month_year_after_part(parsed_hash)
+        return unless parsed_hash[:fips_month_year_after_part]
+
+        combined = parsed_hash[:fips_month_year_after_part]
+        parsed_hash[:second_number] = combined[:second_number]
+        month_str = combined[:edition_month]
+        year_str = combined[:edition_year]
+
+        month_num = month_to_number(month_str)
+        edition_id = month_num&.positive? ? "#{year_str}#{format('%02d', month_num)}" : year_str
+
+        parsed_hash[:edition_from_year] = Components::Edition.new(type: "e", id: edition_id)
+        parsed_hash.delete(:fips_month_year_after_part)
+      end
+
+      # Pattern: "84-2946" with series=IR
+      # For IR (Interagency Report), a 2-digit first_number followed by a
+      # 4-digit dash-year is *almost* always a year-only edition (e.g.
+      # "76e1100") — except when the 4-digit number is clearly not a year
+      # (>= 2700) or there is an embedded :edition_e (compound number).
+      def disambiguate_ir_compound_vs_edition(parsed_hash)
+        return unless safely_to_s(parsed_hash[:series]) == "IR"
+        return unless parsed_hash[:first_number] && parsed_hash[:edition_dash_year]
+
+        first_num = parsed_hash[:first_number].to_s
+        dash_year = parsed_hash[:edition_dash_year][:dash_year].to_s
+        return unless first_num.match?(/^\d{2}$/) && dash_year.match?(/^\d{4}$/)
+
+        dash_year_num = dash_year.to_i
+        is_valid_year = VALID_YEAR_RANGE.cover?(dash_year_num)
+        has_embedded_edition = parsed_hash[:edition_e]
+
+        if is_valid_year && !has_embedded_edition
+          parsed_hash[:first_number] = Components::Code.new(value: first_num)
+          parsed_hash[:edition] = Components::Edition.new(type: "e", id: dash_year)
+        else
+          parsed_hash[:first_number] = Components::Code.new(value: "#{first_num}-#{dash_year}")
+        end
+        parsed_hash.delete(:edition_dash_year)
+      end
+
+      # Pattern: "250-1039" or "15-1000" or "1946-1947" (RPT)
+      # When the parser captures a :first_number plus :edition_dash_year, the
+      # dash year is interpreted differently per series:
+      # - RPT: always join into a compound (date range), regardless of year
+      # - GCR: always convert dash-year to year-only edition
+      # - IR: convert dash-year to year-only edition only if it is a valid year
+      # - HB/CS/FIPS: convert dash-year to year-only edition only if valid year
+      # - others: drop :edition_dash_year, or stash as :second_number if < 1900
+      def disambiguate_dash_year(parsed_hash)
+        return unless parsed_hash[:first_number] && parsed_hash[:edition_dash_year]
+        return if parsed_hash[:first_number].to_s.match?(/^[0-9]+[a-zA-Z]\d+$/)
+
+        dash_year = parsed_hash[:edition_dash_year][:dash_year].to_s
+        series = safely_to_s(parsed_hash[:series])
+        dash_year_num = dash_year.to_i
+        is_valid_year = VALID_YEAR_RANGE.cover?(dash_year_num)
+
+        if series == "RPT"
+          # RPT date ranges: "1946-1947" -> "1946-1947"
+          parsed_hash[:first_number] =
+            Components::Code.new(value: "#{parsed_hash[:first_number]}-#{dash_year}")
+          parsed_hash.delete(:edition_dash_year)
+        elsif series == "GCR"
+          # GCR always converts dash-year to edition
+          stash_edition_from_year(parsed_hash, dash_year)
+        elsif series == "IR" && is_valid_year
+          # IR converts valid years to edition
+          stash_edition_from_year(parsed_hash, dash_year)
+        elsif DASH_YEAR_AS_EDITION_SERIES.include?(series) && is_valid_year
+          # HB/CS/FIPS: convert dash-year to edition only if valid year
+          stash_edition_from_year(parsed_hash, dash_year)
+        elsif dash_year_num < 1900
+          # For other series, dash-year < 1900 is a second_number
+          parsed_hash[:second_number] = dash_year
+          parsed_hash.delete(:edition_dash_year)
+        end
+        # Other cases (non-HB/CS/FIPS with a valid year): leave the keys alone
+        # so downstream Builder logic can handle them.
+      end
+
+      # Convert dash-year into a year-only Edition and stash for the Builder
+      # to assign after construction.
+      def stash_edition_from_year(parsed_hash, dash_year)
+        parsed_hash[:edition_from_year] = Components::Edition.new(type: "e", id: dash_year)
+        parsed_hash.delete(:edition_dash_year)
+      end
+
+      # Safely coerce arbitrary values to strings (parsers can hand us Parslet
+      # nodes that raise on #to_s in some scenarios).
+      def safely_to_s(value)
+        value.to_s
+      rescue StandardError
+        ""
+      end
+
+      # Convert a month abbreviation or name to a 1-based month number.
+      # Returns nil when the value is not a recognizable month.
+      def month_to_number(month_str)
+        Date::ABBR_MONTHNAMES.index(month_str) ||
+          Date::MONTHNAMES.index(month_str) ||
+          month_str.to_i
+      end
+    end
+  end
+end

data/lib/pubid/nist/preprocessor.rb

@@ -0,0 +1,416 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Nist
+    # Owns all regex-based normalization applied to NIST identifier strings
+    # before the Parslet grammar sees them.
+    #
+    # The Parser entry point delegates to Preprocessor#call; the grammar
+    # itself never inspects raw user input. Each private method below is a
+    # named stage of normalization, applied in the order declared in #call.
+    # Stages are kept in the historically validated sequence — reordering
+    # them risks regressions because later stages often match patterns
+    # produced by earlier ones.
+    #
+    # Format detection (:mr vs :short) is also owned here because it is a
+    # property of the original input, not of the parsed tree.
+    class Preprocessor
+      # Outcome of preprocessing.
+      # cleaned - the normalized identifier string ready for the grammar
+      # format  - :mr if the input uses dot-separators, :short otherwise
+      Result = Struct.new(:cleaned, :format, keyword_init: true)
+
+      # Convert Roman numerals to Arabic numbers per NIST spec.
+      ROMAN_TO_ARABIC = {
+        "I" => "1",
+        "II" => "2",
+        "III" => "3",
+        "IV" => "4",
+        "V" => "5",
+        "VI" => "6",
+        "VII" => "7",
+        "VIII" => "8",
+        "IX" => "9",
+        "X" => "10",
+      }.freeze
+
+      def initialize(input)
+        @input = input.to_s.strip
+        @cleaned = Core::UpdateCodes.apply(@input, :nist)
+      end
+
+      # Run every normalization stage and return a Result.
+      #
+      # Stage order is load-bearing — later stages match patterns produced
+      # by earlier ones. Reordering requires running the full NIST fixture
+      # suite to verify no regression.
+      def call
+        run_stages
+        Result.new(cleaned: @cleaned, format: detected_format)
+      end
+
+      # Sequence of normalization stages in historically validated order.
+      # Extracted so rubocop can scope length/ABC metrics narrowly.
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def run_stages
+        normalize_publisher_and_series!
+        normalize_lcirc_supplement_contexts!
+        normalize_revision_spacing!
+        normalize_letter_suffix_casing!
+        normalize_draft_and_volume!
+        convert_roman_volumes!
+        normalize_supplement_and_part!
+        normalize_version_notation!
+        normalize_edition_year_suffix!
+        normalize_revision_with_letter!
+        normalize_version_dotted_spaces!
+        normalize_update_markers!
+        normalize_supplement_variants!
+        normalize_revision_language!
+        normalize_mr_translation_codes!
+        convert_dashyear_to_edition!
+        revert_dashyear_for_series!
+        normalize_version_verbose!
+        normalize_part_notation!
+        normalize_series_specific_spacing!
+        normalize_verbose_keywords!
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+      # Detect input format: :mr (dot-separated machine-readable) or :short.
+      def detected_format
+        @input.include?(".") && !@input.match?(/\s/) ? :mr : :short
+      end
+
+      private
+
+      # Lowercase publishers, publisher+series concatenations, lowercase
+      # series codes, and the lone "LC" → "LCIRC" expansion.
+      def normalize_publisher_and_series!
+        @cleaned = @cleaned.sub(/^nbs\b/i, "NBS")
+        @cleaned = @cleaned.sub(/^nist\b/i, "NIST")
+        @cleaned = @cleaned.gsub(
+          /^(NBS|NIST)(IR|FIPS|GCR|HB|MONO|MP|NCSTAR|NSRDS)/i, '\1 \2'
+        )
+        @cleaned = @cleaned.sub(/\b(ir|sp|tn|hb|fips|ams|vts)\b/i, &:upcase)
+        @cleaned = @cleaned.gsub(/\bLC\b(?!IRC)/, "LCIRC")
+      end
+
+      # LCIRC series: combine with NBS prefix when a supplement marker
+      # follows, and convert MR-format dots to spaces so the grammar's
+      # circ_supplement_identifier rule can match.
+      def normalize_lcirc_supplement_contexts!
+        @cleaned = @cleaned.gsub(
+          /\bNBS LCIRC\b(?=.*\b(?:supp?|sup\+|r\d+\/)\d)/, "NBS.LCIRC"
+        )
+        @cleaned = @cleaned.gsub(
+          /\bNBS\.LCIRC\.(\d+r\d+\/\d{4})/, "NBS LCIRC \\1"
+        )
+        @cleaned = @cleaned.gsub(/\bNBS\.LCIRC\.(\d+r\d+)\b/, "NBS LCIRC \\1")
+      end
+
+      # Separate revision markers from adjacent digits. LCIRC and CIRC
+      # series keep their compact revision form because their grammar
+      # rules expect it.
+      def normalize_revision_spacing!
+        @cleaned = @cleaned.gsub(/([-\d]+[IVX]+[-\d]+)\s+(\d+)/, '\1.\2')
+        @cleaned = @cleaned.gsub(/(?<!e)(\d)(rev\d{4})/, '\1 \2')
+        # Re-parse round-trip: fold dotted edition-date back to canonical
+        # "rev" form so pubid can re-read its own output.
+        @cleaned = @cleaned.gsub(/(\d+e\d+)\.([A-Za-z]{3,9}\d{4})/, '\1rev\2')
+        # IR revision with slash+year is a V1 Update, not a revision.
+        # Must run BEFORE the LCIRC slash rule below so it never adds
+        # a space here.
+        normalize_ir_slash_year_to_update!
+        unless @cleaned.include?("LCIRC") || @cleaned.include?("CIRC")
+          @cleaned = @cleaned.gsub(/(\d)(r\d+\/\d{4})/, '\1 \2')
+        end
+        @cleaned = @cleaned.gsub(/\b(r(?!v)\d{4})\b/, ' \1')
+        @cleaned = @cleaned.gsub(/(\d)(r[A-Z][a-z]{2,8}\d{4})/, '\1 \2')
+      end
+
+      # "5058r04/98" → "5058/Upd1-199804" (mirrors archived v1 NistIr
+      # parser). A 2-digit year normalizes to 19YY. Only applies to IR
+      # series; CIRC/LCIRC keep their slash-year form.
+      def normalize_ir_slash_year_to_update!
+        return unless @cleaned =~ /\bIR\b/ && !@cleaned.include?("CIRC")
+
+        @cleaned = @cleaned.gsub(%r{(\d)r(\d{1,2})/(\d{2,4})}) do
+          num, mon, yr = ::Regexp.last_match(1), ::Regexp.last_match(2), ::Regexp.last_match(3)
+          yyyy = yr.length == 2 ? "19#{yr}" : yr
+          "#{num}/Upd1-#{yyyy}#{format('%02d', mon.to_i)}"
+        end
+      end
+
+      # Uppercase lone letter suffixes attached to numbers. NCSTAR keeps
+      # lowercase volume letters (e.g. "1-1av1") per its grammar.
+      def normalize_letter_suffix_casing!
+        uppercase_dash_letter!
+        uppercase_trailing_letter!
+        uppercase_revision_letter!
+        uppercase_letter_before_revision!
+        uppercase_letter_before_volume! unless @cleaned.include?("NCSTAR")
+      end
+
+      # Trailing "-a" → "-A" at end of identifier.
+      def uppercase_dash_letter!
+        @cleaned = @cleaned.gsub(/(\d)-([a-z])$/) { "#{$1}-#{$2.upcase}" }
+      end
+
+      # Trailing "a" → "A" when attached directly to a digit (excludes
+      # "r" to preserve revision+year patterns like "73-197r").
+      def uppercase_trailing_letter!
+        @cleaned = @cleaned.gsub(/(\d)([a-z&&[^r]])$/) { "#{$1}#{$2.upcase}" }
+      end
+
+      # Letter suffix on revision: "22r1a" → "22r1A".
+      def uppercase_revision_letter!
+        @cleaned = @cleaned.gsub(/(\d)(r)(\d+)([a-z])$/) do
+          "#{$1}#{$2}#{$3}#{$4.upcase}"
+        end
+      end
+
+      # Letter between number and revision: "53ar1" → "53Ar1".
+      def uppercase_letter_before_revision!
+        @cleaned = @cleaned.gsub(/(\d)([a-z])(r\d)/) do
+          "#{$1}#{$2.upcase}#{$3}"
+        end
+      end
+
+      # Letter between number and volume: "1-2bv1" → "1-2Bv1". Skipped
+      # for NCSTAR which preserves lowercase letters per its grammar.
+      def uppercase_letter_before_volume!
+        @cleaned = @cleaned.gsub(/(\d)([a-z&&[^r]])(v\d+)/) do
+          "#{$1}#{$2.upcase}#{$3}"
+        end
+      end
+
+      # Volume/draft spacing and supplement typo fixes that must run
+      # before the more general draft and supplement normalizations.
+      def normalize_draft_and_volume!
+        @cleaned = @cleaned.gsub(/(\d{2}-\d{4})\s+(\d)$/, '\1 v\2')
+        @cleaned = @cleaned.gsub(/(\d)-draft(\d)/, '\1 -draft \2')
+        @cleaned = @cleaned.gsub(/(\d)draft(\d)/, '\1 -draft \2')
+        @cleaned = @cleaned.gsub(/(\d)suprev/, '\1supprev')
+        @cleaned = @cleaned.gsub(
+          /(\d{2,})([A-Z])(r\d+)([-\s]draft\d*)/, '\1\2 \3\4'
+        )
+      end
+
+      # Roman numeral volumes → "v<arabic> ver<version>" per NIST spec.
+      def convert_roman_volumes!
+        @cleaned = @cleaned.gsub(/(\d+)-([IVX]+)-(\d+(?:\.\d+)*)/) do
+          "#{Regexp.last_match(1)} v#{roman_to_arabic(Regexp.last_match(2))} " \
+            "ver#{Regexp.last_match(3)}"
+        end
+      end
+
+      # LCIRC supplement with slash-year separator, and "Pt" part prefix
+      # with revision.
+      def normalize_supplement_and_part!
+        @cleaned = @cleaned.gsub(/(\d)(supp\d+\/\d{4})/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d)Pt(\d+)(r\d+)/, '\1 pt\2 \3')
+      end
+
+      # Version notation: insert spaces between digits and "ver" / "v",
+      # split combined fields, normalize volume ranges.
+      def normalize_version_notation!
+        @cleaned = @cleaned.gsub(/(\d)ver(\d)/, '\1 ver \2')
+        @cleaned = @cleaned.gsub(/ver(\d+)e(\d{4})/, 'ver\1 e\2')
+        @cleaned = @cleaned.gsub(/ver(\d+)v(\d+)/, 'ver\1 v\2')
+        @cleaned = @cleaned.gsub(/(\d)(v\d+\.\d+)/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d)(v\d+\.\d+)/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d)(v\d+)\s+(\d+)$/, '\1 \2.\3')
+        @cleaned = @cleaned.gsub(/(\d)(v\d+)\s+(\d+)\s+(\d+)$/, '\1 \2.\3.\4')
+        @cleaned = @cleaned.gsub(/(\d)(v\d+[a-z]-[a-z])/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d)(v\d+[A-Z])/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(v\d+)([A-Z])-([A-Z])/, '\1\2-\3'.downcase)
+      end
+
+      # Edition year suffix shorthand: "2006ed." → "e2006".
+      def normalize_edition_year_suffix!
+        @cleaned = @cleaned.gsub(/(\d{4})ed\./, 'e\1')
+      end
+
+      # Revision attached to a number with optional letter suffix. When
+      # a letter suffix is present, keep them together for the
+      # second_number grammar rule; otherwise insert a space before
+      # following uppercase letters or update keywords.
+      def normalize_revision_with_letter!
+        @cleaned = @cleaned.gsub(/(\d+)(r\d{1,2})([a-z])(?=-|[A-Z]|$)/) do
+          "#{Regexp.last_match(1)}#{Regexp.last_match(2)}" \
+            "#{Regexp.last_match(3).upcase}"
+        end
+        # rubocop:disable Layout/LineLength
+        @cleaned = @cleaned.gsub(/(\d+)(r\d{1,2})(?![a-zA-Z])(?=[A-Z]|-(?=[A-Z])|\/(?:upd|errata|insert))/) do
+          "#{Regexp.last_match(1)} #{Regexp.last_match(2)}"
+        end
+        # rubocop:enable Layout/LineLength
+      end
+
+      # Dotted versions with internal spaces ("v1 1" → "v1.1"). Negative
+      # lookahead prevents swallowing draft stage digits ("189 2pd").
+      def normalize_version_dotted_spaces!
+        # rubocop:disable Layout/LineLength
+        @cleaned = @cleaned.gsub(/(\b(?:v|\d)[v\d]*[-A-Z]*)\s+(\d+)(?!(?i:pd|wd|prd)\b)\s+(\d+)(?!(?i:pd|wd|prd)\b)/, '\1.\2.\3')
+        @cleaned = @cleaned.gsub(/(\b(?:v|\d)[v\d]*)\s+(\d+)(?!(?i:pd|wd|prd)\b)/, '\1.\2')
+        # rubocop:enable Layout/LineLength
+      end
+
+      # Update markers ("-upd", "/upd") need a space before them so the
+      # grammar's update rule can match.
+      def normalize_update_markers!
+        @cleaned = @cleaned.gsub(/(\d+)-upd(\d*)/, '\1 -upd\2')
+        @cleaned = @cleaned.gsub(/(\d+)\/upd(\d*)/, '\1 /upd\2')
+        @cleaned = @cleaned.gsub(/([a-z]\d+)-upd/, '\1 -upd')
+        @cleaned = @cleaned.gsub(/([a-z]\d+)\/upd/, '\1 /upd')
+        @cleaned = @cleaned.gsub(/(\d+[A-Z])-upd(\d*)/, '\1 -upd\2')
+        @cleaned = @cleaned.gsub(/(\d+[A-Z])\/upd(\d*)/, '\1 /upd\2')
+      end
+
+      # Supplement prefix variants ("sup", "sup+", "supp") all need a
+      # space before them; the "sup" form is normalized to "supp" when
+      # attached to a letter suffix or slash-year.
+      def normalize_supplement_variants!
+        @cleaned = @cleaned.gsub(/(\d)(sup\d)/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d)(sup+)(\d)/, '\1 \2\3')
+        @cleaned = @cleaned.gsub(/(\d)(sup\+)(\d)/, '\1 \2\3')
+        @cleaned = @cleaned.gsub(/(\d)(sup\d+)/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d)(sup\d+\b)/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d+[A-Z])sup(\b)/, '\1supp\2')
+        @cleaned = @cleaned.gsub(/(\d+)sup(\d+\/\d{4})/, '\1supp\2')
+        @cleaned = @cleaned.gsub(/(\d)(supp?)-(\d{4})(?![\d\/])/, '\1supp\3')
+      end
+
+      # Standalone "r" between number-letter and revision, bare trailing
+      # "r" → "r1" (V1 empty-revision normalization), and revision
+      # directly followed by a language code.
+      def normalize_revision_language!
+        @cleaned = @cleaned.gsub(/(\d[a-z])r\b/, '\1 r')
+        @cleaned = @cleaned.gsub(/(\d)r\z/, '\1r1')
+        @cleaned = @cleaned.gsub(
+          /(r\d+)(es|pt|chi|viet|port|esp)\b/, '\1 \2'
+        )
+      end
+
+      # MR-format translation codes (".spa", ".por", ".ind") would be
+      # misparsed as letter suffixes — convert the trailing dot to a space.
+      def normalize_mr_translation_codes!
+        @cleaned = @cleaned.gsub(
+          /^([A-Z]+)\.SP\.(\d+)\.([a-z]{2,4})$/, '\1.SP.\2 \3'
+        )
+        @cleaned = @cleaned.gsub(
+          /^([A-Z]+)\.([A-Z]+)\.(\d+)\.([a-z]{2,4})$/, '\1.\2.\3 \4'
+        )
+      end
+
+      # Trailing "-YYYY" → "eYYYY" edition marker, but only when the
+      # four-digit group is plausibly a year (1901–2099). Part numbers
+      # outside that range (e.g. SP 250-1039) are left untouched.
+      #
+      # The letter suffix may be lower- or uppercase (e.g. SP 800-38b-2005);
+      # it is upcased so the year edition splits off cleanly and the letter
+      # becomes a Part component ("800-38Be2005"), matching how a letter
+      # suffix without a year (800-38a → 800-38A) is already normalized.
+      # "e"/"E" are excluded from the letter so they cannot be confused with
+      # the edition marker itself.
+      def convert_dashyear_to_edition!
+        @cleaned = @cleaned.gsub(
+          /(?<!e\d)(?<![eE-])(\d(?:[A-DF-Za-df-z]?))-(\d{4})(?=\s|$)/,
+        ) do |match|
+          prefix = Regexp.last_match(1)
+          year = Regexp.last_match(2).to_i
+          year.between?(1901, 2099) ? "#{prefix.upcase}e#{year}" : match
+        end
+      end
+
+      # Series-specific reverts: HB handbooks, OWMWP dates, and RPT year
+      # ranges use dash-year structurally (not as an edition marker), so
+      # the broad convert_dashyear_to_edition! rule would corrupt them.
+      def revert_dashyear_for_series!
+        revert_handbook_edition!
+        revert_owmwp_date!
+        revert_report_year_range!
+      end
+
+      # HB handbooks: "HB 130e1979" → "HB 130-1979" (year is part of
+      # the handbook designation, not an edition marker).
+      def revert_handbook_edition!
+        @cleaned = @cleaned.gsub(
+          /\b(HB|HB\s+)[^:\s.]*?(\d+)e(\d{4})(?=\s|$)/, '\1\2-\3'
+        )
+      end
+
+      # OWMWP series: dates use MM-DD-YYYY format, so "OWMWP 06-13e2018"
+      # reverts to "OWMWP 06-13-2018".
+      def revert_owmwp_date!
+        @cleaned = @cleaned.gsub(
+          /\b(OWMWP|OWMWP\s*)[^:\s]*?(\d{2})-(\d{2})e(\d{4})(?=\s|$)/,
+          '\1\2-\3-\4',
+        )
+      end
+
+      # RPT series: year ranges "1946-1947" should not be reinterpreted as
+      # editions. Only revert when the first year precedes the second.
+      def revert_report_year_range!
+        @cleaned = @cleaned.gsub(
+          /\b(RPT|RPT\s*)([^:\s]*?)(\d{4})e(\d{4})(?=\s|$)/,
+        ) { |m| build_report_year_range(m, Regexp.last_match.captures) }
+      end
+
+      # Build the reverted year-range form from the gsub captures, or
+      # return the original match when the years are not a forward range.
+      def build_report_year_range(match, captures)
+        prefix, separator, first, second = captures
+        return match unless first.to_i < second.to_i
+
+        "#{prefix}#{separator}#{first}-#{second}"
+      end
+
+      # Verbose version markers ("v1.1" → "ver1.1", "Ver. 2.0" →
+      # "ver2.0"), MR-format "-v" → ".ver".
+      def normalize_version_verbose!
+        @cleaned = @cleaned.gsub(/-v(\d+\.\d+)/, '.ver\1')
+        @cleaned = @cleaned.gsub(/\bVer\.\s+(\d+(?:\.\d+)*)/, 'ver\1')
+        @cleaned = @cleaned.gsub(/\bv(\d+\.\d+(?:\.\d+)*)/, 'ver\1')
+      end
+
+      # Part notation: uppercase "P" → "p"; lone "p"/"n" → "pt" (unless
+      # followed by a 4-digit year, which is part+year not part-prefix).
+      def normalize_part_notation!
+        @cleaned = @cleaned.gsub(/(\d)P(\d)/, '\1 p\2')
+        @cleaned = @cleaned.gsub(/\b([pn])(\d+)(?!\d{4}\b)/, 'pt\2')
+        @cleaned = @cleaned.gsub(/(\d)([pP]\d+)/, '\1 \2')
+      end
+
+      # Series-specific spacing rules: CRPL-F needs a space after the
+      # letter band; compound report numbers ("17-917v3") need the
+      # volume broken out.
+      def normalize_series_specific_spacing!
+        @cleaned = @cleaned.gsub(/(NBS CRPL-F-[AB])(\d)/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(CRPL-F-[AB])(\d)/, '\1 \2')
+        @cleaned = @cleaned.gsub(/(\d+-\d+)(v\d+)(?![.\d])/, '\1 \2')
+      end
+
+      # Verbose keyword spellings ("Version", "Revision", "Part", "Add",
+      # "Suppl", "report") normalized to their short canonical forms.
+      def normalize_verbose_keywords!
+        @cleaned = @cleaned.gsub(/(\d+)\s+Suppl\b/, '\1Suppl')
+        @cleaned = @cleaned.gsub(/\s+Version\s+(\d+)/, ' ver \1')
+        @cleaned = @cleaned.gsub(/\s+Revision\s+\(r\)/, " r")
+        @cleaned = @cleaned.gsub(/\s+Part\s+(\d+)/, 'pt\1')
+        @cleaned = @cleaned.gsub(/(\d[a-z]?)\s+Add\b\.?/i) do
+          "#{Regexp.last_match(1).upcase} Add."
+        end
+        @cleaned = @cleaned.gsub(/(\d+)\s+rev\s+(\d{4})/, '\1r\2')
+        @cleaned = @cleaned.gsub(/\breport\s*;\s*/, "RPT ")
+        @cleaned = @cleaned.gsub(/\breport\b/, "RPT")
+      end
+
+      # Translate a Roman numeral into its Arabic equivalent.
+      def roman_to_arabic(roman)
+        ROMAN_TO_ARABIC.fetch(roman, roman)
+      end
+    end
+  end
+end