pubid 2.0.0.pre.alpha.9 → 2.0.0.pre.alpha.11

data/lib/pubid/jcgm/urn_parser.rb

@@ -4,31 +4,173 @@ module Pubid
   module Jcgm
     # Parses JCGM URNs back into identifiers.
     #
-    # UrnGenerator emits `urn:jcgm:{number}:{year}` for guides and
-    # `urn:jcgm:meeting:{number}:{year}` for committee/meeting records.
+    # Identifiers are rebuilt **directly from the URN segments** rather than
+    # rendered to a human-readable string and re-parsed (the BIPM UrnParser
+    # pattern). Round-tripping through the grammar flattened the segments into
+    # one string and silently lost everything the string form could not carry:
+    # a GUM guide (`urn:jcgm:gum.6:2020`) raised, and the language and
+    # supplement segments were dropped, so a corrigendum read back as the
+    # standard it amends — a different document, with no error.
     #
-    # Examples:
-    # - urn:jcgm:200:2012 → JCGM 200:2012
-    # - urn:jcgm:100:2008 → JCGM 100:2008
-    # - urn:jcgm:meeting:17:2012 → JCGM 17th Meeting (2012)
+    # Shapes emitted by UrnGenerator, and read back here:
+    #   urn:jcgm:200:2008                        → JCGM 200:2008
+    #   urn:jcgm:100:2008:en                     → JCGM 100:2008(E)
+    #   urn:jcgm:200:2012:en,fr                  → JCGM 200:2012(E/F)
+    #   urn:jcgm:GUM                             → JCGM GUM
+    #   urn:jcgm:gum.6:2020                      → JCGM GUM-6:2020
+    #   urn:jcgm:200:2008:corrigendum            → JCGM 200:2008 Corrigendum
+    #   urn:jcgm:101:2008:corrigendum:1:2009     → JCGM 101:2008/Cor 1:2009
+    #   urn:jcgm:100:2008:amendment:1:2023       → JCGM 100:2008/Amd 1:2023
+    #   urn:jcgm:meeting:17:2012                 → JCGM 17th Meeting (2012)
+    #   urn:jcgm:meeting:11                      → JCGM 11st Meeting
+    #
+    # KNOWN GAP, on the generator side and unchanged here: a full date is
+    # rendered as its year alone (`JCGM GUM-1:2022-11-28` →
+    # `urn:jcgm:gum.1:2022`), so a URN cannot restore the month and day.
+    # Widening it would change already-published URNs.
     class UrnParser < Pubid::UrnParser::Base
+      MEETING_MARKER = "meeting"
+
+      # The GUM-guide number is written "gum.<n>" by UrnGenerator.
+      GUM_PREFIX = "gum."
+
+      # The supplement marker UrnGenerator writes is the typed stage's
+      # `type_code`; the abbreviation is what `Jcgm.locate_stage` matches on.
+      SUPPLEMENT_ABBRS = {
+        "corrigendum" => "Cor",
+        "amendment" => "Amd",
+      }.freeze
+
+      MEETING_ABBR = "Meeting"
+
+      # Mirrors `year_digits` in the shared parser rules.
+      YEAR_PATTERN = /\A(?:19|20)\d{2}\z/
+
+      # A language segment is one or more comma-joined ISO codes.
+      LANGUAGES_PATTERN = /\A[a-z]{2}(?:,[a-z]{2})*\z/
+
+      # Language codes back to the single-letter form the identifier prints;
+      # the builder maps the other way when parsing "(E)" / "(E/F)".
+      LANGUAGE_LETTERS = Pubid::Builder::Base::LANG_CHAR_MAP.invert.freeze
+
       def parse_urn(urn)
         parts = split_parts(strip_namespace(urn))
-        return parse_meeting_urn(parts) if parts.first == "meeting"
+        return parse_meeting_urn(parts) if parts.first == MEETING_MARKER
 
-        number, year = parts
-        text = "JCGM #{number}"
-        text += ":#{year}" if year
-        flavor_parse(text)
+        parse_document_urn(parts)
       end
 
       private
 
-      # urn:jcgm:meeting:<number>:<year> -> "JCGM <ordinal> Meeting (<year>)"
+      # urn:jcgm:meeting:<number>[:<year>] -> Identifiers::Meeting
+      #
+      # The reconstruction must agree with a parsed identifier attribute for
+      # attribute, so `typed_stage` comes from the same registry lookup
+      # `Builder#locate_typed_stage` uses. (The attribute default now agrees
+      # too — it no longer sets `original_abbr` — so this mirrors the builder
+      # for clarity rather than out of necessity.)
       def parse_meeting_urn(parts)
         _, number, year = parts
-        ordinal = Identifiers::Meeting.ordinal(number)
-        flavor_parse("JCGM #{ordinal} Meeting (#{year})")
+
+        Identifiers::Meeting.new(
+          number: meeting_number(number),
+          date: urn_date(year),
+          typed_stage: Jcgm.locate_stage(MEETING_ABBR),
+        )
+      end
+
+      # A guide, a GUM guide, or a supplement wrapping one of those. The
+      # supplement marker splits the segments: everything before it describes
+      # the base document, everything after is the supplement's own number and
+      # date.
+      def parse_document_urn(parts)
+        marker_at = parts.index { |segment| SUPPLEMENT_ABBRS.key?(segment) }
+        return build_document(parts) unless marker_at
+
+        build_supplement(
+          parts[marker_at],
+          build_document(parts[0...marker_at]),
+          parts[(marker_at + 1)..] || [],
+        )
+      end
+
+      # The class comes from the same registry the builder uses, so a URN and a
+      # parsed reference resolve to one class and one typed_stage.
+      def build_supplement(marker, base, tail)
+        typed_stage = Jcgm.locate_stage(SUPPLEMENT_ABBRS.fetch(marker))
+        number, year = tail
+
+        Jcgm.locate_type(typed_stage.type_code).new(
+          base: base,
+          number: (number.nil? || number.empty? ? nil : number.to_s),
+          date: urn_date(year),
+          typed_stage: typed_stage,
+        )
+      end
+
+      # <number>[:<year>][:<languages>] — the number segment carries the
+      # "gum." prefix for a GUM guide, which is what selects the class.
+      #
+      # Guide and GumGuide deliberately take their `typed_stage` from the
+      # attribute default: the grammar emits no type token for them, so
+      # `Builder#build` fills it from `published_typed_stage` too, and both
+      # paths agree.
+      def build_document(parts)
+        number, *rest = parts
+        require_number!(number)
+        gum = number.start_with?(GUM_PREFIX)
+
+        (gum ? Identifiers::GumGuide : Identifiers::Guide).new(
+          number: (gum ? number.delete_prefix(GUM_PREFIX) : number).to_s,
+          date: urn_date(segment_matching(rest, YEAR_PATTERN)),
+          languages: urn_languages(segment_matching(rest, LANGUAGES_PATTERN)),
+        )
+      end
+
+      def require_number!(segment)
+        return unless segment.nil? || segment.empty?
+
+        raise Pubid::UrnParser::Errors::ParseError,
+              "JCGM URN has no document number"
+      end
+
+      def segment_matching(segments, pattern)
+        segments.find { |segment| segment.match?(pattern) }
+      end
+
+      # The ordinal, normalized the way `Identifiers::Meeting.ordinal` does it
+      # (`number.to_i`), so "011" reads back as "11" and a missing or
+      # non-numeric segment as "0" — the behaviour of the previous
+      # render-and-re-parse implementation.
+      def meeting_number(segment)
+        segment.to_i.to_s
+      end
+
+      # nil for an absent year; a Date for a well-formed one. The grammar
+      # accepts only a 19xx/20xx year, so anything else is a malformed URN and
+      # must still be rejected now that no re-parse validates it.
+      def urn_date(segment)
+        return nil if segment.nil? || segment.empty?
+
+        unless segment.match?(YEAR_PATTERN)
+          raise Pubid::UrnParser::Errors::ParseError,
+                "Invalid year in JCGM URN: #{segment.inspect}"
+        end
+
+        Pubid::Components::Date.new(year: segment)
+      end
+
+      # "en" -> (E), "en,fr" -> (E/F). `original_code` is what the renderer
+      # prints, so it is restored from the code rather than left nil.
+      def urn_languages(segment)
+        return nil if segment.nil? || segment.empty?
+
+        segment.split(",").map do |code|
+          Pubid::Components::Language.new(
+            code: code,
+            original_code: LANGUAGE_LETTERS.fetch(code, code),
+          )
+        end
       end
     end
   end

data/lib/pubid/jcgm.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pubid"
 module Pubid
   module Jcgm
     extend Pubid::PrefixesSupport
@@ -22,6 +23,15 @@ module Pubid
     # @param identifier [String] the identifier string to parse
     # @return [Identifier] the parsed identifier
     def self.parse(identifier)
+      unless identifier.is_a?(String)
+        raise Pubid::Errors::InvalidInputError,
+              Pubid::INPUT_NOT_A_STRING_MESSAGE
+      end
+
+      if identifier.length > Pubid::MAX_INPUT_LENGTH
+        raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
+      end
+
       parser = Parser.new
       builder = Builder.new
 

data/lib/pubid/jis/identifier.rb

@@ -175,12 +175,19 @@ module Pubid
       # Parse a JIS identifier string into an identifier object
       # @param identifier [String] The JIS identifier string to parse
       # @return [Identifier] The appropriate identifier object
-      # @raise [RuntimeError] If parsing fails
+      # @raise [Pubid::Errors::ParseError] If parsing fails
       def self.parse(identifier)
+        unless identifier.is_a?(String)
+          raise Pubid::Errors::InvalidInputError,
+                Pubid::INPUT_NOT_A_STRING_MESSAGE
+        end
+
+        if identifier.length > Pubid::MAX_INPUT_LENGTH
+          raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
+        end
+
         parsed = Parser.parse(identifier)
         Builder.build(parsed)
-      rescue Parslet::ParseFailed => e
-        raise "Failed to parse JIS identifier '#{identifier}': #{e.message}"
       end
     end
   end

data/lib/pubid/jis/parser.rb

@@ -4,7 +4,7 @@ require "parslet"
 
 module Pubid
   module Jis
-    class Parser < Parslet::Parser
+    class Parser < ::Pubid::Parser::Grammar
       # Japanese character normalization
       rule(:jp_dash) { str("ｰ") } # Full-width dash
       rule(:jp_space) { str("　") }  # Full-width space

data/lib/pubid/jis.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pubid"
 module Pubid
   module Jis
     extend Pubid::PrefixesSupport

data/lib/pubid/nist/components/stage.rb

@@ -16,10 +16,10 @@ module Pubid
         attribute :id, :string          # i, f, 1-9
         attribute :type, :string        # pd, wd, prd
 
-        # Load stages from V1 YAML config
+        # Load stages from data/nist/stages.yaml
         STAGES = YAML.load_file(
           File.join(File.dirname(__FILE__),
-                    "../../../../archived-gems/pubid-nist/stages.yaml"),
+                    "../../../../data/nist/stages.yaml"),
         ).freeze
 
         # Render stage in specified format

data/lib/pubid/nist/configuration.rb

@@ -58,13 +58,7 @@ module Pubid
       private
 
       def default_series_path
-        # Prefer data/nist/series.yaml (the canonical home in the monorepo);
-        # fall back to archived-gems/pubid-nist/series.yaml for backward
-        # compat with the v1 layout.
-        monorepo = File.join(__dir__, "../../../data/nist/series.yaml")
-        return monorepo if File.exist?(monorepo)
-
-        File.join(__dir__, "../../../archived-gems/pubid-nist/series.yaml")
+        File.join(__dir__, "../../../data/nist/series.yaml")
       end
 
       def load_series
@@ -78,6 +72,10 @@ module Pubid
       end
     end
 
-    class ConfigurationError < StandardError; end
+    # Raised when the NIST series YAML cannot be loaded. Included in the
+    # marker module so `rescue Pubid::Errors::Error` stays exhaustive.
+    class ConfigurationError < StandardError
+      include ::Pubid::Errors::Error
+    end
   end
 end

data/lib/pubid/nist/identifiers/base.rb

@@ -170,6 +170,10 @@ module Pubid
       end
 
       def initialize(**attributes)
+        # This override calls `super()` with no attributes and assigns through
+        # setters instead, so it bypasses the base constructor's coercion and
+        # unknown-key check. Apply them here to keep the cross-flavor contract.
+        attributes = self.class.normalize_init_attributes(attributes)
         super()
 
         attrs = self.class.attributes
@@ -304,13 +308,19 @@ module Pubid
       # @param format [:full, :long, :abbreviated, :short, :mr] output format
       def to_s(format = nil)
         # Handle both keyword argument (hash) and positional argument (symbol/string)
+        annotated = format.is_a?(Hash) ? format[:annotated] : nil
         format = format[:format] if format.is_a?(Hash)
 
         # Default to parsed_format if available (preserves input format on round-trip)
         # Falls back to :short format for output (normalization)
         # Explicit format parameter always overrides parsed_format
-        render(format: :human,
-               nist_format: format || parsed_format&.to_sym || :short)
+        rendered = render(format: :human,
+                          nist_format: format || parsed_format&.to_sym || :short)
+
+        # NIST's `to_s` takes a POSITIONAL format and its `render` override
+        # builds no rendering context, so neither the flag nor the context
+        # reaches the shared hook. Apply the annotation fallback here.
+        annotate_plain_render(rendered, annotated: annotated)
       end
 
       # NIST has its own defined MR format (to_mr_style) used by relaton-nist

data/lib/pubid/nist/identifiers/circular.rb

@@ -53,7 +53,14 @@ module Pubid
         # Override to_s for CIRC-specific edition+year rendering
         # CIRC uses dot notation: "NBS CIRC 11e2.1915" instead of "NBS CIRC 11e2-1915"
         def to_s(format = nil)
-          result = super
+          # The rewrite below is `$`-anchored, so it has to run on the PLAIN
+          # string: with the flag set, `super` returns a string ending in
+          # "</span>" and the anchor no longer matches. Render plain, rewrite,
+          # then annotate.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+          format = format[:format] if format.is_a?(Hash)
+
+          result = super(format)
 
           # For CIRC edition patterns with additional_text (year), render with dot notation
           # "11e2-1915" format: edition.id="2", additional_text="1915" → render as "11e2.1915"
@@ -65,7 +72,7 @@ module Pubid
                                  "e#{edition.id || '?'}.#{edition.additional_text}")
           end
 
-          result
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/circular_supplement.rb

@@ -37,13 +37,22 @@ module Pubid
         attribute :implicit_supplement, :boolean # true for implicit supplements (e.g., "145r11/1925")
 
         def to_s(format = :short)
+          # A caller passing `annotated:` reaches this positional parameter as a
+          # Hash. Normalise it away before `super`, so the annotation is applied
+          # once, here, and covers the date-range branch too — that branch
+          # returns a hand-composed string and never reached `super` at all.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+          format = format[:format] || :short if format.is_a?(Hash)
+
           # Handle date range supplements (no base identifier)
-          if supplement_date_range_start && supplement_date_range_end
-            return "NBS CIRC sup#{supplement_date_range_start}-#{supplement_date_range_end}"
-          end
+          result = if supplement_date_range_start && supplement_date_range_end
+                     "NBS CIRC sup#{supplement_date_range_start}-#{supplement_date_range_end}"
+                   else
+                     # Use parent's rendering for base + supplement
+                     super(format)
+                   end
 
-          # Use parent's rendering for base + supplement
-          super
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/commercial_standards_monthly.rb

@@ -41,6 +41,12 @@ module Pubid
         end
 
         def to_s(format = nil)
+          # A caller passing `annotated:` reaches this positional parameter as
+          # a Hash — Ruby converts keywords for a method that accepts none.
+          # The same idiom `Identifiers::Base#to_s` uses. This renderer
+          # ignores `format`, so only the flag is read.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+
           result = "#{publisher} #{series}"
 
           # Proper Volume and Part components
@@ -55,7 +61,7 @@ module Pubid
             result += " #{vol_str}n#{issue_number.number}"
           end
 
-          result
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/crpl_report.rb

@@ -88,6 +88,12 @@ module Pubid
         end
 
         def to_s(format = nil)
+          # A caller passing `annotated:` reaches this positional parameter as
+          # a Hash — Ruby converts keywords for a method that accepts none.
+          # The same idiom `Identifiers::Base#to_s` uses. This renderer
+          # ignores `format`, so only the flag is read.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+
           # Use actual series attribute if it contains subseries (e.g., "CRPL-F-B")
           # Otherwise use default series_code ("CRPL")
           series_to_render = if series&.value&.include?("CRPL-F-")
@@ -124,7 +130,7 @@ module Pubid
           result += append_short_components
 
           result += range_notation if range_notation
-          result
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/handbook.rb

@@ -34,8 +34,15 @@ module Pubid
         # Override to_s to handle edition+year pattern with dash instead of dot
         # Pattern: "44e2-1955" (dash separator) not "44e2.1955" (dot separator)
         def to_s(format = nil)
+          # The rewrite below is `$`-anchored, so it has to run on the PLAIN
+          # string: with the flag set, `super` returns a string ending in
+          # "</span>" and the anchor no longer matches. Render plain, rewrite,
+          # then annotate.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+          format = format[:format] if format.is_a?(Hash)
+
           # Use the base to_s method first
-          result = super
+          result = super(format)
 
           # If edition has additional_text (year), replace dot with dash
           if edition&.additional_text && !edition.additional_text.empty?
@@ -43,7 +50,7 @@ module Pubid
                                  "#{edition.type}#{edition.id}-#{edition.additional_text}")
           end
 
-          result
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/internal_report.rb

@@ -37,6 +37,11 @@ module Pubid
         # @param format [Symbol, Hash, nil] output format
         # @return [String] formatted identifier
         def to_s(format = nil)
+          # `super` is handed a SYMBOL below, so the base's annotation hook
+          # never sees the flag. Capture it here and wrap what comes back —
+          # exactly once, because the base returned plain text.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+
           # Handle both keyword argument (hash) and positional argument (symbol/string)
           effective_format = if format.is_a?(Hash)
                                format[:format]
@@ -45,11 +50,13 @@ module Pubid
                              end
 
           # If explicit format is specified, use it. Otherwise, default to short.
-          if effective_format.nil?
-            super(:short)
-          else
-            super(effective_format)
-          end
+          rendered = if effective_format.nil?
+                       super(:short)
+                     else
+                       super(effective_format)
+                     end
+
+          annotate_plain_render(rendered, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/miscellaneous_publication.rb

@@ -36,13 +36,21 @@ module Pubid
           "MP"
         end
 
+        # A caller passing `annotated:` reaches this positional parameter as a
+        # Hash — Ruby converts keywords for a method that accepts none. The same
+        # idiom `Identifiers::Base#to_s` uses.
         def to_s(format = :short)
-          case format
-          when :mr
-            to_mr_style
-          else
-            to_short_style
-          end
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+          format = format[:format] || :short if format.is_a?(Hash)
+
+          rendered = case format
+                     when :mr
+                       to_mr_style
+                     else
+                       to_short_style
+                     end
+
+          annotate_plain_render(rendered, annotated: annotated)
         end
 
         public

data/lib/pubid/nist/identifiers/monograph.rb

@@ -35,6 +35,11 @@ module Pubid
         end
 
         def to_s(format = nil)
+          # `super` is handed a SYMBOL below, so the base's annotation hook
+          # never sees the flag. Capture it here and wrap what comes back —
+          # exactly once, because the base returned plain text.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+
           # Handle both keyword argument (hash) and positional argument (symbol/string)
           effective_format = if format.is_a?(Hash)
                                format[:format]
@@ -43,13 +48,15 @@ module Pubid
                              end
 
           # If explicit format is specified, use it. Otherwise, default to short.
-          if effective_format.nil?
-            super(:short)
-          elsif effective_format == :mr
-            to_mr_style
-          else
-            super(effective_format)
-          end
+          rendered = if effective_format.nil?
+                       super(:short)
+                     elsif effective_format == :mr
+                       to_mr_style
+                     else
+                       super(effective_format)
+                     end
+
+          annotate_plain_render(rendered, annotated: annotated)
         end
 
         private

data/lib/pubid/nist/identifiers/report.rb

@@ -39,13 +39,21 @@ module Pubid
           "RPT"
         end
 
+        # A caller passing `annotated:` reaches this positional parameter as a
+        # Hash — Ruby converts keywords for a method that accepts none. The same
+        # idiom `Identifiers::Base#to_s` uses.
         def to_s(format = :short)
-          case format
-          when :mr
-            to_mr_style
-          else
-            to_short_style
-          end
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+          format = format[:format] || :short if format.is_a?(Hash)
+
+          rendered = case format
+                     when :mr
+                       to_mr_style
+                     else
+                       to_short_style
+                     end
+
+          annotate_plain_render(rendered, annotated: annotated)
         end
 
         private

data/lib/pubid/nist/parser.rb

@@ -6,7 +6,7 @@ module Pubid
   module Nist
     # Parser class for NIST identifiers
     # Single Responsibility: Parsing NIST identifier syntax
-    class Parser < Parslet::Parser
+    class Parser < ::Pubid::Parser::Grammar
 
       # Class-level parse method with preprocessing.
       # Delegates all string normalization to Nist::Preprocessor, then

data/lib/pubid/nist/supplement_identifier.rb

@@ -25,13 +25,28 @@ module Pubid
         base&.series
       end
 
+      # Four exits — a date range, a base-less delegation, an update form and
+      # the canonical one — so the composition stays whole in its own method
+      # and `to_s` wraps its single result. `super` is not reachable from a
+      # private method, so it is handed in as a block.
       def to_s(format = :short)
+        annotated = format.is_a?(Hash) ? format[:annotated] : nil
+        format = format[:format] || :short if format.is_a?(Hash)
+
+        rendered = render_plain(format) { super(format) }
+
+        annotate_plain_render(rendered, annotated: annotated)
+      end
+
+      private
+
+      def render_plain(format)
         # Handle date range supplements (no base identifier)
         if supplement_date_range_start && supplement_date_range_end
           return "NBS CIRC sup#{supplement_date_range_start}-#{supplement_date_range_end}"
         end
 
-        return super unless base
+        return yield unless base
 
         result = base.to_s(format)
 

data/lib/pubid/nist.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pubid"
 module Pubid
   module Nist
     extend Pubid::PrefixesSupport
@@ -67,8 +68,13 @@ module Pubid
     # @param identifier [String] the identifier string to parse
     # @return [Identifier] the parsed identifier
     def self.parse(identifier)
+      unless identifier.is_a?(String)
+        raise Pubid::Errors::InvalidInputError,
+              Pubid::INPUT_NOT_A_STRING_MESSAGE
+      end
+
       if identifier.length > Pubid::MAX_INPUT_LENGTH
-        raise ArgumentError, Pubid::INPUT_TOO_LONG_MESSAGE
+        raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
       end
 
       # Use the Parser class's preprocessing method