pubid 2.0.0.pre.alpha.1 → 2.0.0.pre.alpha.2

data/lib/pubid/jcgm/identifier.rb

@@ -6,6 +6,49 @@ module Pubid
       def self.parse(string)
         Pubid::Jcgm.parse(string)
       end
+
+      # Factory mirroring pubid 1.x's `Pubid::Jcgm::Identifier.create` API.
+      # Dispatches `:guide` (default) → Guide, `:gum_guide` → GumGuide.
+      TYPE_KEY_TO_KLASS = {
+        guide:     "Guide",
+        gum_guide: "GumGuide",
+      }.freeze
+
+      def self.create(type: nil, **opts)
+        klass = resolve_create_class(type)
+        attrs = coerce_create_attrs(opts)
+        ts = klass.const_defined?(:TYPED_STAGES) &&
+             klass.const_get(:TYPED_STAGES).find do |t|
+               t.stage_code&.to_sym == :published
+             end
+        attrs[:typed_stage] = ts if ts
+        klass.new(**attrs)
+      end
+
+      def self.resolve_create_class(type)
+        return Identifiers::Guide if type.nil?
+
+        klass_name = TYPE_KEY_TO_KLASS[type.to_sym]
+        raise ArgumentError, "Unknown JCGM type: #{type.inspect}" unless klass_name
+
+        Identifiers.const_get(klass_name)
+      end
+
+      def self.coerce_create_attrs(opts)
+        attrs = {
+          publisher: Pubid::Jcgm::Components::Publisher.new(
+            publisher: (opts[:publisher] || "JCGM").to_s,
+          ),
+        }
+        if (v = opts[:number])
+          attrs[:number] = Pubid::Components::Code.new(value: v.to_s)
+        end
+        if (v = opts[:year])
+          attrs[:date] = Pubid::Components::Date.new(year: v.to_s)
+        end
+        attrs
+      end
+      private_class_method :resolve_create_class, :coerce_create_attrs
     end
   end
 end

data/lib/pubid/jis/identifier.rb

@@ -13,6 +13,49 @@ module Pubid
       rescue Parslet::ParseFailed => e
         raise "Failed to parse JIS identifier '#{identifier}': #{e.message}"
       end
+
+      # Factory mirroring pubid 1.x's `Pubid::Jis::Identifier.create` API.
+      #
+      # JIS uses a different attribute schema from most flavors — `series`
+      # (single letter A–Z), `number` (integer), `parts` (integer collection),
+      # `year` (integer), `language`. Publisher is hardcoded "JIS" on the
+      # instance and not a constructor kwarg; supplying `:publisher` is
+      # silently ignored.
+      #
+      # Type dispatch: :jis → Standard, :tr → TechnicalReport,
+      # :ts → TechnicalSpecification. Default → Standard.
+      def self.create(type: nil, **opts)
+        klass = if type
+                  safe_locate_klass(type) || Identifiers::Standard
+                else
+                  Identifiers::Standard
+                end
+        klass.new(**coerce_create_attrs(opts))
+      end
+
+      # JIS Scheme raises ArgumentError on miss; wrap.
+      def self.safe_locate_klass(type)
+        Scheme.locate_identifier_klass_by_type_code(type)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.coerce_create_attrs(opts)
+        attrs = {}
+        attrs[:series] = opts[:series].to_s if opts[:series]
+        attrs[:number] = opts[:number].to_i if opts[:number]
+        if opts[:parts]
+          attrs[:parts] = Array(opts[:parts]).map(&:to_i)
+        end
+        attrs[:code] = opts[:code] if opts[:code]
+        attrs[:year] = opts[:year].to_i if opts[:year]
+        attrs[:language] = opts[:language].to_s if opts[:language]
+        attrs[:all_parts] = opts[:all_parts] if opts.key?(:all_parts)
+        # TODO(create-shim): :publisher silently ignored (JIS hardcodes
+        # "JIS"); supplement subclasses not yet wired through.
+        attrs
+      end
+      private_class_method :safe_locate_klass, :coerce_create_attrs
     end
   end
 end

data/lib/pubid/nist/builder.rb

@@ -369,10 +369,30 @@ module Pubid
         part_num = nil
         extracted_revision = nil
 
+        # Accumulate supplement signals from the casts (a flat value string,
+        # the has_revision flag, and date-range start/end) and fold them into a
+        # single Components::Supplement at the end. They are intercepted (not
+        # assigned) because :supplement is now a component attribute, so a raw
+        # string must never be written to it directly.
+        supp = { value: nil, has_revision: false, range_start: nil,
+                 range_end: nil, present: false }
+        capture_supplement = lambda do |k, v|
+          case k
+          when :supplement then supp[:value] = v
+          when :supplement_has_revision then supp[:has_revision] = !!v
+          when :supplement_date_range_start then supp[:range_start] = v
+          when :supplement_date_range_end then supp[:range_end] = v
+          else return false
+          end
+          supp[:present] = true
+          true
+        end
+
         # Cast and assign all attributes
         parsed_hash.each_pair do |key, value|
           realized_components = cast(key.to_sym, value, parsed_hash) # Pass parsed_hash for context
           next if realized_components.nil?
+          next if !realized_components.is_a?(Hash) && capture_supplement.call(key.to_sym, realized_components)
 
           # Track number components
           if key == :first_number && realized_components.is_a?(Components::Code)
@@ -427,6 +447,10 @@ module Pubid
               # Skip assignment for second_number hashes - they'll be processed during compound number construction
               next if sub_key == :second_number && sub_value.is_a?(Hash) && sub_value[:number_only]
 
+              # Intercept supplement signals into the accumulator instead of
+              # assigning them (supplement is now a component built at the end).
+              next if capture_supplement.call(sub_key, sub_value)
+
               attrs = identifier.class.attributes
               setter = "#{sub_key}="
               if attrs.key?(sub_key.to_sym)
@@ -543,7 +567,16 @@ module Pubid
               year_part = second_num.value.to_s
 
               identifier.number = Components::Code.new(number: number_part)
-              identifier.supplement = year_part
+              supp[:value] = year_part
+              supp[:present] = true
+            elsif second_num.value.to_s.match?(/^(\d+)supp?$/)
+              # Pattern: "800-53sup"/"800-53supp" - bare marker on the compound
+              # second number. Strip it and isolate as supplement="" (single-p).
+              second_part = second_num.value.to_s.match(/^(\d+)supp?$/)[1]
+              compound = "#{first_num.value}-#{second_part}"
+              identifier.number = Components::Code.new(number: compound)
+              supp[:value] = ""
+              supp[:present] = true
             elsif identifier.is_a?(Identifiers::TechnicalNote) &&
                 second_num.value.to_s.match?(/^(19|20)\d{2}$/)
               # SPECIAL CASE FOR TN: second_num is edition year
@@ -633,9 +666,41 @@ module Pubid
           identifier.revision_month = nil
         end
 
+        # Fold the accumulated supplement signals into the single structured
+        # supplement component (the source of truth).
+        if (supp[:present] || supp[:has_revision]) &&
+            identifier.respond_to?(:supplement=)
+          identifier.supplement = supplement_from(
+            value: supp[:value], has_revision: supp[:has_revision],
+            range_start: supp[:range_start], range_end: supp[:range_end]
+          )
+        end
+
         identifier
       end
 
+      # Build a Components::Supplement from the builder's accumulated raw signals
+      # (flat value string, has_revision flag, fused date-range start/end). This
+      # is the one place raw supplement text becomes the structured component.
+      def supplement_from(value:, has_revision:, range_start:, range_end:)
+        if range_start || range_end
+          component = Components::Supplement.new
+          # Split the fused "Jun1925"/"Jun1926" strings into isolated start/end
+          # month+year nodes (start reuses :month/:year, end uses *_end).
+          if range_start && (m = range_start.match(/\A([A-Za-z]{3,9})(\d{4})\z/))
+            component.month = m[1]
+            component.year = m[2]
+          end
+          if range_end && (m = range_end.match(/\A([A-Za-z]{3,9})(\d{4})\z/))
+            component.month_end = m[1]
+            component.year_end = m[2]
+          end
+          component
+        else
+          Components::Supplement.from_raw(value, has_revision: has_revision)
+        end
+      end
+
       # Convert month name to month number
       # @param month_name [String] month abbreviation (Jan, Feb, Mar, etc.)
       # @return [Integer] month number (1-12)
@@ -659,8 +724,109 @@ module Pubid
 
       # Build CircularSupplement with base_identifier wrapping
       # @param parsed_hash [Hash] the parsed supplement data
-      # @return [Identifiers::CircularSupplement] the supplement identifier
+      # Build a CIRC/LCIRC supplement. Most forms collapse onto the base
+      # identifier's normal class (Circular / LetterCircular) with isolated
+      # supplement attributes, so they share one model with every other series
+      # and are queryable by part. The V1-compat update forms (slash-year
+      # "118supp3/1926" → ".../Upd1-192603"; implicit revision "145r11/1925")
+      # render through an Update component the flat supplement model can't
+      # express, so they stay on the CircularSupplement wrapper for now.
       def build_circular_supplement(parsed_hash)
+        if parsed_hash[:supplement_slash_year].is_a?(Hash) ||
+            parsed_hash[:implicit_supplement].is_a?(Hash)
+          return build_circular_supplement_wrapper(parsed_hash)
+        end
+
+        series_value = if parsed_hash[:circ_series].is_a?(Hash)
+                         parsed_hash[:circ_series][:series]
+                       else
+                         parsed_hash[:series]
+                       end
+
+        # Date-range supplement (no base document): a plain base identifier with
+        # no number, carrying the range. parsed_format is left at the default so
+        # a dotted MR input still normalizes to the spaced short form.
+        if parsed_hash[:supplement_date_range].is_a?(Hash)
+          range = parsed_hash[:supplement_date_range]
+          identifier = build({ series: series_value })
+          ms = range[:supp_month_start]&.to_s
+          ys = range[:supp_year_start]&.to_s
+          me = range[:supp_month_end]&.to_s
+          ye = range[:supp_year_end]&.to_s
+          identifier.supplement = supplement_from(
+            value: nil, has_revision: false,
+            range_start: (ms && ys ? "#{ms}#{ys}" : nil),
+            range_end: (me && ye ? "#{me}#{ye}" : nil)
+          )
+          return identifier
+        end
+
+        # Based supplement: build the base, then attach the supplement as an
+        # isolated component on that normal class.
+        identifier = build_circular_supplement_base(parsed_hash, series_value)
+        raw = if parsed_hash[:supplement_month_year]
+                parsed_hash[:supplement_month_year].to_s
+              elsif parsed_hash[:supplement_year]
+                parsed_hash[:supplement_year].to_s
+              else
+                "" # supplement_empty or bare marker
+              end
+        identifier.supplement = Components::Supplement.from_raw(raw)
+        identifier
+      end
+
+      # Build just the base identifier for a based CIRC/LCIRC supplement, from
+      # base_portion (number, optional edition "101e2" or letter suffix "378G")
+      # or the merged first_number fallback. Returns the normal class.
+      def build_circular_supplement_base(parsed_hash, series_value)
+        base_portion = parsed_hash[:base_portion]
+        unless base_portion
+          return build({
+                         publisher: parsed_hash[:publisher],
+                         series: series_value || parsed_hash[:series],
+                         first_number: parsed_hash[:first_number],
+                         parsed_format: parsed_hash[:parsed_format],
+                       })
+        end
+
+        base_number = if base_portion.is_a?(Hash)
+                        base_portion[:simple_number] || base_portion[:base_number]
+                      else
+                        base_portion
+                      end
+
+        letter_suffix = nil
+        if base_portion.is_a?(Hash) && base_portion[:letter_suffix]
+          letter_suffix = base_portion[:letter_suffix].to_s.upcase
+        end
+
+        publisher_value = nil
+        if parsed_hash[:circ_series].is_a?(Hash) && parsed_hash[:circ_series][:series]
+          series_str = parsed_hash[:circ_series][:series].to_s
+          publisher_value = series_str.split.first if series_str.include?(" ")
+        end
+
+        has_edition = base_portion.is_a?(Hash) && base_portion[:edition_number]
+
+        base_number_with_suffix = base_number.to_s
+        base_number_with_suffix += letter_suffix if letter_suffix
+        if has_edition
+          base_number_with_suffix += "e#{base_portion[:edition_number]}"
+        end
+
+        base_hash = {
+          series: series_value,
+          first_number: base_number_with_suffix,
+          parsed_format: parsed_hash[:parsed_format],
+        }
+        base_hash[:publisher] = publisher_value if publisher_value
+        base_hash[:edition_e] = { edition_id: base_portion[:edition_number] } if has_edition
+
+        build(base_hash)
+      end
+
+      # @return [Identifiers::CircularSupplement] the supplement identifier
+      def build_circular_supplement_wrapper(parsed_hash)
         supplement = Identifiers::CircularSupplement.new
 
         # Extract series from circ_series if present (nested structure from parser)
@@ -1066,9 +1232,12 @@ module Pubid
               end
             end
 
-            # NEW: Pattern "9350sup" - number with "sup" suffix (no year)
-            # This handles RPT supplements like "NBS RPT 9350sup"
-            if str_value =~ /^(\d+)sup$/
+            # Pattern "9350sup"/"5893supp" - number with bare supplement marker
+            # (no trailing payload). Accept both single-p "sup" and double-p
+            # "supp" so the marker is isolated as supplement="" and rendered as
+            # canonical single-p "sup", instead of staying baked into the number
+            # as an opaque suffix. E.g. "NBS RPT 5893supp", "NBS MONO 32supp".
+            if str_value =~ /^(\d+)supp?$/
               return {
                 first_number: Components::Code.new(number: $1),
                 supplement: "",

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

@@ -49,6 +49,22 @@ module Pubid
           end
         end
 
+        # Identity ignores original_prefix: it records how the edition was
+        # spelled in the source ("Rev. " vs "r") for round-trip rendering
+        # only. "r1" and "Rev. 1" are the same edition.
+        def ==(other)
+          return false unless other.is_a?(self.class)
+
+          type == other.type && id == other.id &&
+            additional_text == other.additional_text
+        end
+
+        alias eql? ==
+
+        def hash
+          [self.class, type, id, additional_text].hash
+        end
+
         private
 
         # Build short format: "e2", "e2.June1908", "e2.1908", "e2.50", "r1963", "-April1909", "r1a"

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

@@ -9,17 +9,19 @@ module Pubid
       # Represents supplement notation with number, year, month, or revision
       #
       # Examples:
-      #   Supplement.new(number: "2").to_s(:short)              # => "supp2"
-      #   Supplement.new(year: "1925").to_s(:short)              # => "supp-1925"
-      #   Supplement.new(number: "3", year: "1926").to_s(:short) # => "supp3/1926"
-      #   Supplement.new(month: "Jan", year: "1924").to_s(:short) # => "suppJan1924"
-      #   Supplement.new(has_revision: true).to_s(:short)        # => "supprev"
+      #   Supplement.new(number: "2").to_s(:short)              # => "sup2"
+      #   Supplement.new(year: "1925").to_s(:short)              # => "sup1925"
+      #   Supplement.new(number: "3", year: "1926").to_s(:short) # => "sup3/1926"
+      #   Supplement.new(month: "Jan", year: "1924").to_s(:short) # => "supJan1924"
+      #   Supplement.new(has_revision: true).to_s(:short)        # => "suprev"
       class Supplement < Lutaml::Model::Serializable
         attribute :number, :string           # Supplement number (e.g., "2" in "supp2")
-        attribute :year, :string             # Year (4 digits)
-        attribute :month, :string            # Month abbreviation (Jan, Feb, etc.)
-        attribute :month_start, :string       # Date range start month
-        attribute :year_start, :string        # Date range start year
+        attribute :year, :string             # Year (4 digits); range START year
+        attribute :month, :string            # Month abbreviation; range START month
+        # Date ranges reuse :month/:year as the start and add the end below. A
+        # present :month_end/:year_end is what marks a value as a range, so a
+        # lone month-year supplement is just a range with no end — and :year is
+        # the single field to filter on for both.
         attribute :month_end, :string         # Date range end month
         attribute :year_end, :string          # Date range end year
         attribute :has_revision, :boolean, default: -> {
@@ -27,12 +29,36 @@ module Pubid
         } # "supprev" pattern
         attribute :suffix, :string # General suffix for other patterns
 
+        # Build a Supplement from the flat string the parser/builder produces
+        # ("1924" year, "Jan1924" month+year, "1" number, "A" suffix, "" bare).
+        # has_revision is supplied separately. Returns a present-but-empty
+        # Supplement for an empty/nil value so callers can distinguish a bare
+        # supplement ("sup") from no supplement (nil).
+        def self.from_raw(value, has_revision: false)
+          supp = new
+          if has_revision
+            supp.has_revision = true
+          elsif value.nil? || value.to_s.empty?
+            # bare marker: present but no isolated parts
+          elsif (m = value.to_s.match(/\A([A-Za-z]{3,9})(\d{4})\z/))
+            supp.month = m[1]
+            supp.year = m[2]
+          elsif value.to_s.match?(/\A(?:18|19|20)\d{2}\z/)
+            supp.year = value.to_s
+          elsif value.to_s.match?(/\A\d+\z/)
+            supp.number = value.to_s
+          else
+            supp.suffix = value.to_s
+          end
+          supp
+        end
+
         # Render supplement in specified format
         # @param format [:short, :mr, :long] The output format
         # @return [String] The formatted supplement representation
         def to_s(format = :short)
-          return "" if number.nil? && year.nil? && !has_revision && suffix.nil? &&
-            month_start.nil? && year_start.nil? && month_end.nil? && year_end.nil?
+          return "" if number.nil? && year.nil? && month.nil? && !has_revision &&
+            suffix.nil? && month_end.nil? && year_end.nil?
 
           case format
           when :short, :mr
@@ -44,12 +70,52 @@ module Pubid
           end
         end
 
+        # True when this supplement is a date range (start reuses month/year).
+        def range?
+          date_range?
+        end
+
+        # The text after the "sup" marker for the simple (non-range, non-rev)
+        # forms: "1924" / "Jan1924" / "1" / "A"; "" for a bare supplement. Used
+        # by URN rendering, which handles range/revision separately.
+        def value_string
+          return "" if has_revision || date_range?
+          return suffix.to_s if suffix
+          return "#{month}#{year}" if month && year
+          return "#{number}/#{year}" if number && year
+          return year.to_s if year
+          return number.to_s if number
+
+          ""
+        end
+
+        # Value equality over the isolated parts, so a structured supplement
+        # participates correctly in Identifier#== and #matches? (two supplements
+        # with the same number/year/month/range/revision are the same).
+        IDENTITY_FIELDS = %i[
+          number year month month_end year_end has_revision suffix
+        ].freeze
+
+        def ==(other)
+          return false unless other.is_a?(self.class)
+
+          IDENTITY_FIELDS.all? { |f| send(f) == other.send(f) }
+        end
+
+        alias eql? ==
+
+        def hash
+          [self.class, *IDENTITY_FIELDS.map { |f| send(f) }].hash
+        end
+
         private
 
-        # Build short format: "supp2", "supp-1925", "supp3/1926", "suppJan1924", "supprev"
+        # Build short format: "sup2", "sup1925", "sup3/1926", "supJan1924", "suprev"
+        # NIST/NBS canonical short form is single-p "sup" with the suffix
+        # attached directly (relaton-data-nist uses "sup2", "sup1940", "supA").
         def build_short_format
-          return "supprev" if has_revision
-          return "supp#{suffix}" if suffix
+          return "suprev" if has_revision
+          return "sup#{suffix}" if suffix
           return build_date_range_format if date_range?
           return build_month_year_format if month && year
           return build_number_year_format if number && year
@@ -72,32 +138,33 @@ module Pubid
           ""
         end
 
+        # A range is marked by the presence of an END; START reuses month/year.
         def date_range?
-          month_start && year_start && month_end && year_end
+          month && year && month_end && year_end
         end
 
         def build_date_range_format
-          "supp#{month_start}#{year_start}-#{month_end}#{year_end}"
+          "sup#{month}#{year}-#{month_end}#{year_end}"
         end
 
         def build_month_year_format
-          "supp#{month}#{year}"
+          "sup#{month}#{year}"
         end
 
         def build_number_year_format
-          "supp#{number}/#{year}"
+          "sup#{number}/#{year}"
         end
 
         def build_year_format
-          "supp-#{year}"
+          "sup#{year}"
         end
 
         def build_number_format
-          "supp#{number}"
+          "sup#{number}"
         end
 
         def build_long_date_range_format
-          "Supplement #{month_start} #{year_start}-#{month_end} #{year_end}"
+          "Supplement #{month} #{year}-#{month_end} #{year_end}"
         end
 
         def build_long_month_year_format

data/lib/pubid/nist/identifier.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Nist
+    # NIST factory entry point. `.parse` lives on `Pubid::Nist` itself for
+    # historical reasons; this module hosts `.create` for API consistency
+    # with the other pubid flavors.
+    module Identifier
+      # Delegate to the flavor module so callers can use
+      # `Pubid::Nist::Identifier.parse` consistently with other flavors.
+      def self.parse(identifier)
+        Pubid::Nist.parse(identifier)
+      end
+
+      # Factory mirroring pubid 1.x's `Pubid::Nist::Identifier.create` API.
+      #
+      # Dispatch is by `:series` (e.g. "SP", "FIPS", "IR", "HB", "TN")
+      # rather than a type code — NIST organises identifiers by document
+      # series. {Scheme.locate_identifier_klass} handles the mapping,
+      # including compound prefixes like "NBS CIRC" and special cases
+      # (CSM, CS-E, etc.).
+      def self.create(**opts)
+        klass = Scheme.locate_identifier_klass(
+          series: opts[:series]&.to_s,
+        ) || Identifiers::Base
+        klass.new(**coerce_create_attrs(opts))
+      end
+
+      def self.coerce_create_attrs(opts)
+        attrs = {}
+        if (v = opts[:publisher])
+          attrs[:publisher] = Pubid::Nist::Components::Publisher.new(
+            publisher: v.to_s,
+          )
+          # NIST renderer prints the publisher only when it was parsed
+          # (or explicitly flagged as such).
+          attrs[:publisher_was_parsed] = true
+        end
+
+        attrs[:series] = wrap_code(opts[:series]) if opts[:series]
+        attrs[:number] = wrap_code(opts[:number]) if opts[:number]
+
+        %i[edition volume part stage version_component update_component
+           translation_component issue_number].each do |k|
+          attrs[k] = opts[k] unless opts[k].nil?
+        end
+
+        # TODO(create-shim): expose primitive coercion for edition/volume/
+        # part etc. once a caller needs it; for now pass-through accepts
+        # already-built NIST Components.
+        attrs
+      end
+
+      def self.wrap_code(v)
+        return v if v.is_a?(Pubid::Nist::Components::Code)
+
+        Pubid::Nist::Components::Code.new(number: v.to_s)
+      end
+      private_class_method :coerce_create_attrs, :wrap_code
+    end
+  end
+end