pubid 2.0.0.pre.alpha.8 → 2.0.0.pre.alpha.11

data/lib/pubid/csa/identifiers/combined.rb

@@ -5,16 +5,23 @@ require "lutaml/model"
 module Pubid
   module Csa
     module Identifiers
-      # CombinedIdentifier represents CSA identifiers combined with "/" separator
+      # Combined represents CSA identifiers joined with "/" or ", "
       # Examples:
       #   CSA A23.1:24/CSA A23.2:24
       #   CSA N285.0:23/CSA N285.6 SERIES:23
       #   CSA A123.1-05/A123.5-05 (R2015)
       #   CSA B44:19/B44.1:19/B44.2:19 (triple combined)
-      class Combined < Lutaml::Model::Serializable
-        attribute :first, Standard
-        attribute :second, Standard
-        attribute :third, Standard
+      class Combined < Identifier
+        # The co-equal designations, in printed order.
+        #
+        # One polymorphic collection, the IEC ConsolidatedIdentifier shape —
+        # not the historical first/second/third triple, which hard-capped the
+        # form at three and froze a non-standard hash shape. The first member
+        # is the primary designation, which is what #root walks so the index
+        # key is non-empty. Typed cross-flavor for the same reason as
+        # WrapperIdentifier#base.
+        attribute :identifiers, ::Pubid::Identifier, polymorphic: true,
+                                                     collection: true
         attribute :reaffirmation, :string
         attribute :original_reaffirmation_4digit, :boolean, default: -> {
           false
@@ -23,61 +30,74 @@ module Pubid
         attribute :year_format, :string # Dummy for compatibility
         attribute :separator, :string, default: -> { "/" } # "/" or ", "
 
-        def to_s
-          # For comma separator, render both parts with full prefix
-          # For slash separator, second/third parts without prefix
-          if separator == ", "
-            # Comma: Both with full CSA prefix
-            parts = [first.to_s, second.to_s]
-            parts << third.to_s if third
-          else
-            # Slash: Second and third without CSA prefix (continuation)
-            parts = [first.to_s]
-            parts << render_continuation(second)
-            parts << render_continuation(third) if third
-          end
+        # A combined id stores its members in `identifiers`, not `base`, so
+        # walk the primary designation to the origin document
+        # (Iec::Identifiers::ConsolidatedIdentifier does the same).
+        def root
+          identifiers&.first&.root || self
+        end
 
-          result = parts.join(separator || "/")
+        # Co-equal designations, so both matching primitives reduce to the
+        # primary one — the Iec::Identifiers::ConsolidatedIdentifier shape.
+        def base_document
+          identifiers&.first&.base_document || self
+        end
 
-          # Reaffirmation - preserve original format and determine spacing
-          if reaffirmation
-            # For combined identifiers, check year format from first identifier
-            # to determine spacing
-            year_was_2digit = first.class.attributes.key?(:original_year_4digit) && !first.original_year_4digit
-
-            # Check if reaffirmation was originally 4-digit
-            # Note: We need to track this at the Combined level, but for now
-            # assume 4-digit if the value is 4 digits and starts with 19/20
-            reaffirmation_was_4digit = reaffirmation.to_s.length == 4 &&
-              reaffirmation.to_s.start_with?("19", "20")
-
-            # Determine spacing based on original formats
-            # Space needed if year is 2-digit and reaffirmation is 4-digit
-            result += if year_was_2digit && reaffirmation_was_4digit
-                        " (R#{reaffirmation})"
-                      else
-                        "(R#{reaffirmation})"
-                      end
-          end
+        def drop_supplements
+          identifiers&.first || self
+        end
 
+        def to_s(**opts)
+          parts = render_parts
+          result = parts.join(separator || "/")
+          result += render_reaffirmation if reaffirmation
           result += package if package
-          result
+          annotate_plain_render(result, **opts)
         end
 
         private
 
+        # With a comma separator every designation carries its full prefix;
+        # with a slash the trailing ones are continuations printed bare.
+        def render_parts
+          return identifiers.map(&:to_s) if separator == ", "
+
+          identifiers.each_with_index.map do |identifier, index|
+            index.zero? ? identifier.to_s : render_continuation(identifier)
+          end
+        end
+
+        # Reaffirmation - preserve original format and determine spacing.
+        # A space is needed when the year was printed 2-digit and the
+        # reaffirmation 4-digit; the year format comes from the primary
+        # designation.
+        def render_reaffirmation
+          primary = identifiers&.first
+          year_was_2digit =
+            primary &&
+            primary.class.attributes.key?(:original_year_4digit) &&
+            !primary.original_year_4digit
+
+          reaffirmation_was_4digit = reaffirmation.to_s.length == 4 &&
+            reaffirmation.to_s.start_with?("19", "20")
+
+          if year_was_2digit && reaffirmation_was_4digit
+            " (R#{reaffirmation})"
+          else
+            "(R#{reaffirmation})"
+          end
+        end
+
         # Render identifier without CSA prefix (unless has_publisher is true)
         def render_continuation(identifier)
           parts = []
 
           # Add CSA prefix if present in original
           if identifier.has_publisher
-            prefix = identifier.publisher_prefix || "CSA"
-            !prefix.end_with?("-")
-            parts << prefix
+            parts << (identifier.publisher_prefix || "CSA")
           end
 
-          code_part = identifier.code.to_s if identifier.code
+          code_part = identifier.number.to_s if identifier.number
 
           # NO. keyword
           if identifier.no_number
@@ -92,34 +112,42 @@ module Pubid
             code_part += " SERIES"
           end
 
-          # Year with proper format (colon or dash)
-          if identifier.year
-            separator = identifier.year_format == "dash" ? "-" : ":"
-            year_part = separator
-            year_part += identifier.year_prefix if identifier.year_prefix # Add M or F prefix
-            year_part += "F" if identifier.french && identifier.year_format != "dash" && !identifier.year_prefix # Only add F if no prefix
-            # Convert 4-digit year back to 2-digit
-            year_str = identifier.year.to_s
-            year_part += if year_str.length == 4 && year_str.start_with?("20")
-                           year_str[2..3]
-                         else
-                           year_str
-                         end
-            code_part += year_part
-          end
+          code_part += render_continuation_year(identifier) if identifier.year
 
           parts << code_part if code_part
 
-          # Join with proper spacing based on prefix
-          if identifier.has_publisher && parts.length > 1
-            prefix = parts[0]
-            needs_space = !prefix.end_with?("-")
-            if needs_space
-              parts.join(" ")
-            else
-              # No space after dash-ending prefix
-              parts[0] + parts[1..].join(" ")
-            end
+          join_continuation(identifier, parts)
+        end
+
+        # Year with proper format (colon or dash)
+        def render_continuation_year(identifier)
+          separator = identifier.year_format == "dash" ? "-" : ":"
+          year_part = separator
+          # Add M or F prefix
+          year_part += identifier.year_prefix if identifier.year_prefix
+          # Only add F if no prefix
+          if identifier.french && identifier.year_format != "dash" &&
+              !identifier.year_prefix
+            year_part += "F"
+          end
+          # Convert 4-digit year back to 2-digit
+          year_str = identifier.year.to_s
+          year_part + if year_str.length == 4 && year_str.start_with?("20")
+                        year_str[2..3]
+                      else
+                        year_str
+                      end
+        end
+
+        # Join with proper spacing based on prefix
+        def join_continuation(identifier, parts)
+          return parts.join(" ") unless identifier.has_publisher &&
+            parts.length > 1
+
+          prefix = parts[0]
+          if prefix.end_with?("-")
+            # No space after dash-ending prefix
+            prefix + parts[1..].join(" ")
           else
             parts.join(" ")
           end

data/lib/pubid/csa/identifiers/csa_adopted.rb

@@ -18,16 +18,16 @@ module Pubid
       #
       # This is a wrapper pattern where:
       #   - CSA prefix indicates adoption
-      #   - The wrapped_identifier is the external standard (ISO/IEC/CISPR)
+      #   - The base is the external standard (ISO/IEC/CISPR)
       #   - Wrapped identifier is recursively parsed using external flavor parsers
       class CsaAdopted < WrapperIdentifier
         # Publisher prefix (e.g., "CSA-", "CAN3-") for rendering
         # When set, uses dash format without space (e.g., "CSA-ISO" not "CSA ISO")
         attribute :publisher_prefix, :string
 
-        def to_s
+        def to_s(**opts)
           # Get string representation from wrapped identifier
-          base_str = wrapped_identifier.to_s
+          base_str = base.to_s
 
           # Convert 4-digit years to 2-digit for CSA adoption format
           # ISO/IEC TR 12785-3:2015 → ISO/IEC TR 12785-3:15
@@ -70,7 +70,7 @@ module Pubid
           # Append reaffirmation if present
           result += " (R#{reaffirmation})" if reaffirmation
 
-          result
+          annotate_plain_render(result, **opts)
         end
       end
     end

data/lib/pubid/csa/identifiers/package.rb

@@ -12,7 +12,7 @@ module Pubid
       #   CSA C22.2 NO. 60601-1:15 PACKAGE WITH ADDENDUM
       #
       # This is a composite pattern where:
-      #   - base_identifier is the core CSA standard (recursively parsed)
+      #   - base is the core CSA standard (recursively parsed)
       #   - package_materials describes what's included in the package
       #   - Package portion is metadata, not a parseable identifier
       #
@@ -33,8 +33,8 @@ module Pubid
         # false = materials BEFORE: "CSA B149.1:25 Code, Handbook & Training Package"
         attribute :materials_after_keyword, :boolean, default: -> { true }
 
-        def to_s
-          result = base_identifier.to_s
+        def to_s(**opts)
+          result = base.to_s
 
           # Add package materials if present
           if package_materials && !package_materials.empty?
@@ -57,7 +57,7 @@ module Pubid
             result += " PACKAGE"
           end
 
-          result
+          annotate_plain_render(result, **opts)
         end
       end
     end

data/lib/pubid/csa/parser.rb

@@ -4,7 +4,7 @@ require "parslet"
 
 module Pubid
   module Csa
-    class Parser < Parslet::Parser
+    class Parser < ::Pubid::Parser::Grammar
       # Basic building blocks
       rule(:space) { str(" ") }
       rule(:dash) { str("-") }
@@ -179,7 +179,7 @@ module Pubid
           # Optional series prefix (MH, RV, etc.) before SERIES keyword
           (series_prefix >> space).maybe >>
           series_keyword.as(:series_type) >>
-          (colon_year | dash_year) >>
+          (colon_year | dash_year).maybe >>
           reaffirmation.maybe
       end
 
@@ -194,7 +194,7 @@ module Pubid
           ).as(:cec_part) >>
           no_notation >>
           no_number >>
-          (colon_year | dash_year) >>
+          (colon_year | dash_year).maybe >>
           reaffirmation.maybe
       end
 
@@ -257,7 +257,7 @@ module Pubid
             (space >> series_keyword.as(:series) >> (colon_year | dash_year)) |
             # Option 4: just year (no series, no NO.)
             (colon_year | dash_year)
-          ) >>
+          ).maybe >> # trailing year optional (partial reference)
           amendment_slash.maybe # Add amendment support here
       end
 
@@ -274,7 +274,7 @@ module Pubid
             (space >> series_keyword.as(:series) >> (colon_year | dash_year)) |
             # Option 4: just year
             (colon_year | dash_year)
-          )
+          ).maybe # trailing year optional (partial reference)
       end
 
       # Continuation code (optional CSA publisher prefix, for combined identifiers)
@@ -290,7 +290,7 @@ module Pubid
             (space >> series_keyword.as(:series) >> (colon_year | dash_year)) |
             # Option 4: just year
             (colon_year | dash_year)
-          ) >>
+          ).maybe >> # trailing year optional (partial reference)
           amendment_slash.maybe
       end
 
@@ -353,7 +353,7 @@ module Pubid
             (space >> series_keyword.as(:series) >> (colon_year | dash_year)) |
             # Option 3: just year
             (colon_year | dash_year)
-          ) >>
+          ).maybe >> # trailing year optional (partial reference)
           (space >> str("PACKAGE")).as(:package_portion).maybe
       end
 
@@ -367,7 +367,11 @@ module Pubid
       # Preprocessing to normalize input
       def parse(input)
         # Skip comment lines
-        raise Parslet::ParseFailed.new("Comment line") if input.strip.start_with?("#")
+        if input.strip.start_with?("#")
+          raise Pubid::Errors::ParseError.new(
+            "Comment line", input: input, flavor: "csa"
+          )
+        end
 
         # Remove CONSOLIDATED notation FIRST (before other processing)
         normalized = input.gsub(/\s*\(\s*CONSOLIDATED\s*\)\s*/, " ")

data/lib/pubid/csa/renderer.rb

@@ -35,7 +35,7 @@ module Pubid
 
       # Base rendering: "CSA B149.1:20", "CAN/CSA-C22.2-05"
       def render_base(id)
-        prefix = id.publisher_prefix || "CSA"
+        prefix = publisher_prefix_for(id)
 
         # Handle code_only identifiers (empty string means no prefix)
         if prefix == ""
@@ -51,7 +51,7 @@ module Pubid
         end
 
         # Code and year together
-        code_part = id.code.to_s if id.code
+        code_part = id.number.to_s if id.number
 
         # NO. keyword
         if id.no_number
@@ -131,7 +131,7 @@ module Pubid
         parts = []
 
         # Publisher prefix (CSA, CAN/CSA-, CAN3-)
-        prefix = id.publisher_prefix || "CSA"
+        prefix = publisher_prefix_for(id)
 
         # Determine if we need space after prefix
         # CAN/CSA- and CAN3- end with dash, so no space needed
@@ -203,7 +203,7 @@ module Pubid
         result = series_publisher_prefix_portion(id)
 
         # Add code FIRST (before SERIES keyword)
-        result += id.code.to_s
+        result += id.number.to_s
 
         # Add space before series prefix/SERIES keyword
         result += " "
@@ -255,8 +255,16 @@ module Pubid
         end
       end
 
+      # The publisher prefix to print. A code_only identifier printed none, so
+      # it must not gain the default "CSA" — see SingleIdentifier#code_only.
+      def publisher_prefix_for(id)
+        return "" if id.respond_to?(:code_only) && id.code_only
+
+        id.publisher_prefix || "CSA"
+      end
+
       def series_publisher_prefix_portion(id)
-        prefix = id.publisher_prefix || "CSA"
+        prefix = publisher_prefix_for(id)
 
         # Handle code_only identifiers (empty string means no prefix)
         return "" if prefix == ""

data/lib/pubid/csa/single_identifier.rb

@@ -3,11 +3,18 @@
 module Pubid
   module Csa
     class SingleIdentifier < Identifier
-      # Generate URN for this identifier
+      # The document code — "B149.1", "Z240", "C22.2" — and the relaton index
+      # key: Relaton::Index sorts and bsearches every row on
+      # `id.root.number.to_s`, so it must never be empty.
       #
-      # @return [String] URN representation
-
-      attribute :code, Components::Code
+      # It is the `number` INHERITED from ::Pubid::Identifier, not a
+      # redeclaration: Pubid::Csa::Components::Code is a bare alias of
+      # Pubid::Components::Code, which is exactly the parent's declared type.
+      # That matters. CSA's base is split across two files (csa/identifier.rb +
+      # csa/single_identifier.rb) — the IEEE shape in which a leaf can snapshot
+      # a half-built parent attribute table (CLAUDE.md, the `number`
+      # determinism landmine). Declaring nothing here keeps CSA clear of it.
+      # The attribute was named `code` before; there is no alias.
       attribute :no_number, :string
       attribute :year, :string
       attribute :year_format, :string  # "colon" or "dash"
@@ -25,6 +32,88 @@ module Pubid
       attribute :series, :boolean         # Track if SERIES keyword present
       attribute :package, :string         # Package portion (Code, Handbook, etc.)
       attribute :publisher_prefix, :string # Original prefix: "CAN/CSA-", "CSA", "CAN3-"
+
+      # True when the reference printed no publisher at all ("C22.1-15"), so
+      # rendering must not supply the default "CSA".
+      #
+      # This used to be an empty-string `publisher_prefix` sentinel, which the
+      # canonical `to_hash` drops (it strips empty and default-valued
+      # attributes by design) — so a code-only identifier came back
+      # from `from_hash` with a nil prefix and re-rendered as
+      # "CSA C22.1-15". Named for the RARE case with a `false` default,
+      # per CLAUDE.md, so it is dropped from every ordinary row.
+      attribute :code_only, :boolean, default: -> { false }
+
+      # A flat, index-friendly serialized shape: the `Components::Code`
+      # attributes collapse to bare scalars (`number: C22.2-286`, not
+      # `number: {value: C22.2-286}`), the ISO/ETSI/ITU `key_value` pattern.
+      #
+      # This is deliberately a serialization mapping rather than an
+      # `attribute :number, :string` redeclaration. CSA's base is split across
+      # two files (csa/identifier.rb + csa/single_identifier.rb) — the IEEE
+      # shape in which a leaf can snapshot a half-built parent attribute table
+      # — so a retype here would reintroduce the `number` determinism landmine
+      # recorded in CLAUDE.md. The runtime attribute stays a Components::Code;
+      # only the hash is flat.
+      #
+      # A lutaml key_value block is EXHAUSTIVE — an unmapped attribute is
+      # dropped, `_type` included — so every attribute above appears here. It
+      # lives on SingleIdentifier, which only the single-document types
+      # inherit; the container types descend from Csa::Identifier directly and
+      # keep the default shape for their nested `base`/`identifiers`.
+      key_value do
+        map "_type", to: :_type
+        map "number", with: { to: :number_to_kv, from: :number_from_kv }
+        map "no_number",
+            with: { to: :no_number_to_kv, from: :no_number_from_kv }
+        map "year", to: :year
+        map "year_format", to: :year_format
+        map "year_prefix", to: :year_prefix
+        map "original_year_4digit", to: :original_year_4digit
+        map "french", to: :french
+        map "reaffirmation", to: :reaffirmation
+        map "original_reaffirmation_4digit", to: :original_reaffirmation_4digit
+        map "has_publisher", to: :has_publisher
+        map "series_prefix", to: :series_prefix
+        map "series", to: :series
+        map "package", to: :package
+        map "publisher_prefix", to: :publisher_prefix
+        map "code_only", to: :code_only
+      end
+
+      def number_to_kv(model, doc)
+        emit_kv(doc, "number", model.number)
+      end
+
+      def number_from_kv(model, value)
+        model.number = Components::Code.new(value: value.to_s)
+      end
+
+      # `no_number` is a plain :string here but a Components::Code on Cec, so
+      # the converter reads through whichever it is given.
+      def no_number_to_kv(model, doc)
+        emit_kv(doc, "no_number", model.no_number)
+      end
+
+      def no_number_from_kv(model, value)
+        model.no_number =
+          if model.class.attributes[:no_number].type == Components::Code
+            Components::Code.new(value: value.to_s)
+          else
+            value.to_s
+          end
+      end
+
+      # Emit a scalar, skipping a nil or empty value so the canonical
+      # no-defaults hash never gains an empty key.
+      def emit_kv(doc, key, value)
+        text = value.respond_to?(:value) ? value.value : value
+        return if text.nil? || text.to_s.empty?
+
+        doc.add_child(
+          Lutaml::KeyValue::DataModel::Element.new(key, text.to_s),
+        )
+      end
     end
   end
 end

data/lib/pubid/csa/urn_generator.rb

@@ -3,16 +3,23 @@
 module Pubid
   module Csa
     class UrnGenerator < Pubid::UrnGenerator::Base
+      # A code_only identifier printed no publisher, so it keeps an empty
+      # publisher segment rather than falling back to "csa" in #generate.
       def urn_publisher_prefix
+        return "" if code_only?
         return nil unless identifier.publisher_prefix
 
         identifier.publisher_prefix.to_s.downcase
       end
 
+      def code_only?
+        identifier.respond_to?(:code_only) && identifier.code_only
+      end
+
       def urn_number
-        return nil unless identifier.code
+        return nil unless identifier.number
 
-        identifier.code.render(context: URN_CONTEXT)
+        identifier.number.render(context: URN_CONTEXT)
       end
 
       def urn_no_number

data/lib/pubid/csa/wrapper_identifier.rb

@@ -4,28 +4,61 @@ require "lutaml/model"
 
 module Pubid
   module Csa
-    # WrapperIdentifier is the base class for all CSA identifiers that wrap other identifiers
+    # WrapperIdentifier is the base class for all CSA identifiers that wrap
+    # other identifiers.
     # Examples:
-    #   - CanadianAdoptedIdentifier: CAN/{wrapped_identifier}
-    #   - CsaAdoptedIdentifier: CSA {ISO/IEC/CISPR identifier}
+    #   - CanadianAdopted: CAN/{base}
+    #   - CsaAdopted:      CSA {ISO/IEC/CISPR identifier}
     #
-    # The wrapper pattern allows proper MODEL-DRIVEN architecture where adoptions
-    # are objects that contain other identifier objects, not string prefixes.
-    class WrapperIdentifier < Lutaml::Model::Serializable
-      # The wrapped identifier (recursively parsed)
-      # Use attr_accessor since it can be any identifier object (CSA, ISO, IEC, etc.)
-      attr_accessor :wrapped_identifier
+    # The wrapper pattern allows proper MODEL-DRIVEN architecture where
+    # adoptions are objects that contain other identifier objects, not string
+    # prefixes.
+    class WrapperIdentifier < Identifier
+      # The wrapped identifier (recursively parsed).
+      #
+      # A real lutaml attribute, not an attr_accessor: the accessor was
+      # invisible to `to_hash`, `from_hash` AND `#exclude` (which iterates
+      # `self.class.attributes`), so a wrapper serialized to a hash with no
+      # identifier in it at all. It is named `base` — the uniform parent
+      # accessor every flavor uses — so the inherited `#root` walks it to the
+      # origin document and `exclude_from_nested` reaches inside. There is no
+      # `wrapped_identifier` alias.
+      #
+      # Typed as the cross-flavor `::Pubid::Identifier`, not the CSA one:
+      # CsaAdopted wraps ISO/IEC/CISPR ids, and lutaml enforces the declared
+      # type — `polymorphic: true` widens it only to SUBCLASSES, so a narrower
+      # type raises Lutaml::Model::IncorrectModelError on `to_hash`. The
+      # Ieee::Identifiers::AdoptedStandard precedent. The nested child carries
+      # its own `_type`, so `from_hash` routes it back via TypeResolver.
+      attribute :base, ::Pubid::Identifier, polymorphic: true
 
       # Reaffirmation year (common across wrappers)
       attribute :reaffirmation, :string
 
+      # Whether the reaffirmation was printed 4-digit ("(R2004)") rather than
+      # 2-digit ("(R04)"). CanadianAdopted#to_s reads it to choose the spacing
+      # and to render the year back in its original width.
+      attribute :original_reaffirmation_4digit, :boolean, default: -> { false }
+
       # Year format tracking (for compatibility)
       attribute :year_format, :string
 
       # Subclasses MUST implement to_s
-      def to_s
+      def to_s(**_opts)
         raise NotImplementedError, "Subclasses must implement to_s method"
       end
+
+      # The matching primitives relaton uses to normalise a reference before
+      # comparing it. An adoption wrapper peels to the document it adopts;
+      # without these the inherited defaults return the WRAPPER, which is a
+      # silently wrong answer rather than a loud one.
+      def base_document
+        base ? base.base_document : self
+      end
+
+      def drop_supplements
+        base || self
+      end
     end
   end
 end

data/lib/pubid/csa.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pubid"
 module Pubid
   module Csa
     extend Pubid::PrefixesSupport
@@ -20,8 +21,13 @@ module Pubid
     autoload :Components, "#{__dir__}/csa/components"
 
     def self.parse(identifier_string)
+      unless identifier_string.is_a?(String)
+        raise Pubid::Errors::InvalidInputError,
+              Pubid::INPUT_NOT_A_STRING_MESSAGE
+      end
+
       if identifier_string.length > Pubid::MAX_INPUT_LENGTH
-        raise ArgumentError, Pubid::INPUT_TOO_LONG_MESSAGE
+        raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
       end
 
       Identifier.parse(identifier_string)

data/lib/pubid/doi/builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Doi
+    class Builder
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        Identifiers::Resource.new(
+          prefix: "10.#{data[:prefix]}",
+          suffix: data[:suffix].to_s,
+        )
+      end
+    end
+  end
+end