pubid 2.0.0.pre.alpha.9 → 2.0.0.pre.alpha.12

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

@@ -27,7 +27,7 @@ module Pubid
       #     bare { "value" => … } with no part;
       #   - drop the redundant build artifacts, decomposed pieces of the
       #     canonical number that identity/rendering never read.
-      COMPACT_FLAT_CODES = %w[series number subseries].freeze
+      COMPACT_FLAT_CODES = %w[series subseries].freeze
       COMPACT_FLAT_VALUES = %w[volume].freeze
       COMPACT_DROP_ATTRS = %w[first_number second_number].freeze
 
@@ -105,7 +105,14 @@ module Pubid
       # equality so a manually-built id (without subseries set) still equals a
       # parsed one.
       attribute :subseries, Components::Code
-      attribute :number, Components::Code
+      # Plain :string. NIST never populated the Code beyond `value`: `subpart`
+      # is set nowhere, and `part` was a reader splitting `value` on "-" that
+      # no library code called. `series`, `subseries`, `first_number`,
+      # `second_number` and `parts` keep the component.
+      attribute :number, :string
+      # NIST never uses `subpart`; declare it so the inherited Components::Code
+      # does not disagree with this class (the determinism landmine).
+      attribute :subpart, :string
 
       # V2 COMPONENTS (Lutaml::Model objects) - PROPER SEPARATION
       # `edition` (Components::Edition: type + id + additional_text) is the
@@ -170,6 +177,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 +315,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
@@ -402,7 +419,7 @@ module Pubid
         # "National Institute of Standards and Technology Special Publication 800-27, Revision A"
         result = publisher_full_name
         result += " #{series_full_name}" if series
-        result += " #{number.value}" if number
+        result += " #{number}" if number
         result += parts.map { |p| "-#{p}" }.join if parts&.any?
 
         # Render volume and issue number in long form: "Vol. 6, No. 12"

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_standard_emergency.rb

@@ -44,7 +44,7 @@ module Pubid
           result += " CS-E"
 
           # Number (already extracted from e104 → 104 in builder)
-          result += " #{number.value}" if number
+          result += " #{number}" if number
 
           # Edition (e1943 for e104-43 pattern) plus any other component the
           # parser attached (volume, supplement, version, ...).

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

@@ -46,7 +46,7 @@ module Pubid
         def normalized_number
           return nil unless number
 
-          num_value = number.value.to_s
+          num_value = number.to_s
 
           # Pattern: c4-4 → 4-4 (hide 'c' prefix)
           case num_value
@@ -64,12 +64,12 @@ module Pubid
         end
 
         # Override number to return normalized value
-        # Tests expect number.value to be normalized (c4-4 → 4-4, 4-m-5 → 4-M-5)
+        # Tests expect number to be normalized (c4-4 → 4-4, 4-m-5 → 4-M-5)
         def number
           num = super
           return num unless num
 
-          num_value = num.value.to_s
+          num_value = num.to_s
 
           # Pattern: c4-4 → 4-4 (hide 'c' prefix)
           case num_value
@@ -83,11 +83,16 @@ module Pubid
             num_value = num_value.gsub(/^m-/, "M-")
           end
 
-          # Return new Code object with normalized value
-          Components::Code.new(value: num_value)
+          num_value
         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-")
@@ -100,7 +105,7 @@ module Pubid
 
           if number
             # Normalize number value for CRPL patterns
-            num_value = number.value.to_s
+            num_value = number.to_s
 
             # Pattern: c4-4 → 4-4 (hide 'c' prefix)
             case num_value
@@ -124,7 +129,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/federal_information_processing_standards.rb

@@ -66,14 +66,14 @@ module Pubid
             # Convert dash-year patterns to edition format for FIPS
             # Pattern: "14-1971" → "14e1971" (edition year format)
             # But preserve dash for parts: "140-3" stays as-is
-            if number.value =~ /^(\d{1,3})-(\d{4})$/
+            if number =~ /^(\d{1,3})-(\d{4})$/
               # This is a number-year pattern (e.g., "14-1971")
               # Convert to edition format: "14e1971"
               number_part = $1
               year_part = $2
               result += " #{number_part}e#{year_part}"
             else
-              result += " #{number.value}"
+              result += " #{number}"
             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,27 +36,35 @@ 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
 
         def to_short_style
           result = "#{default_publisher} #{series_code}"
-          result += " #{number.value}" if number
+          result += " #{number}" if number
           result += append_short_components
           result
         end
 
         def to_mr_style
           result = "#{default_publisher}.#{series_code}"
-          result += ".#{number.value}" if number
+          result += ".#{number}" if number
           result += append_mr_components
           result
         end

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/series/ir.rb

@@ -31,9 +31,7 @@ module Pubid
                                              letter_suffix:)
           return false unless letter_suffix == "R"
 
-          identifier.number = Components::Code.new(
-            value: "#{first_num.value}-#{letter_base}",
-          )
+          identifier.number = "#{first_num.value}-#{letter_base}"
           edition_obj = Components::Edition.new(type: "r", id: "1")
           identifier.edition = edition_obj
           true
@@ -42,13 +40,11 @@ module Pubid
         def self.finalize_identifier(identifier, _parsed_hash)
           return unless identifier.number
 
-          value = identifier.number.value.to_s
+          value = identifier.number.to_s
           match = value.match(/^(\d+)e(\d{4})$/)
           return unless match
 
-          identifier.number = Components::Code.new(
-            value: "#{match[1]}-#{match[2]}",
-          )
+          identifier.number = "#{match[1]}-#{match[2]}"
           identifier.edition = nil
         end
       end

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

data/lib/pubid/oasis/builder.rb

@@ -4,15 +4,17 @@ module Pubid
   module Oasis
     # Turns the parse tree into an `Identifiers::Standard`: stores the slug
     # verbatim in `original`, then performs a best-effort, ORDER-INDEPENDENT
-    # decomposition into spec / version / stage / part / label.
+    # decomposition into number / version / stage / part / label.
     #
     # Decomposition splits `original` on "-" and classifies each *whole*
     # fragment (so a stage-like substring inside a spec name — e.g. "CSDL" — is
-    # never mistaken for a stage). `spec` is the run of leading name fragments
-    # before the first recognized fragment; `version`/`stage`/`part` are the
-    # first fragment of each recognized kind; `label` is any name fragment
-    # appearing after the first recognized one. Anything the classifier cannot
-    # place stays only in `original`, so the printed form always round-trips.
+    # never mistaken for a stage). `number` is the specification name: the run
+    # of leading name fragments before the first recognized fragment, and the
+    # key relaton-index sorts and binary-searches on. `version`/`stage`/`part`
+    # are the first fragment of each recognized kind; `label` is any name
+    # fragment appearing after the first recognized one. Anything the
+    # classifier cannot place stays only in `original`, so the printed form
+    # always round-trips.
     class Builder
       # A fragment is a version when it is `v?N(.N)+` (e.g. "3.0", "v1.2.1",
       # "V1.0"). Bare integers are deliberately NOT versions (too ambiguous
@@ -36,16 +38,16 @@ module Pubid
 
       private
 
-      # @return [Hash] best-effort { spec:, version:, stage:, part:, label: }.
-      # Each fragment is classified once into a [fragment, kind] pair. `spec` is
-      # the leading run of name fragments; `label` is any name fragment after
+      # @return [Hash] best-effort { number:, version:, stage:, part:, label: }.
+      # Each fragment is classified once into a [fragment, kind] pair. `number`
+      # is the leading run of name fragments; `label` is any name fragment after
       # the first recognized one; version/stage/part are the first of each kind.
       def decompose(original)
         pairs = original.split("-").map { |f| [f, classify(f)] }
         lead = pairs.take_while { |_, kind| kind.nil? }
         rest = pairs.drop(lead.length)
         {
-          spec: names(lead),
+          number: names(lead),
           version: first_of(rest, :version),
           stage: first_of(rest, :stage),
           part: first_of(rest, :part),