pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/utils/string_normalizer.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Utils
+    # String normalization utilities for PubID parsing and rendering
+    #
+    # This module provides centralized string manipulation methods
+    # to reduce duplication and improve consistency.
+    #
+    # == Usage
+    #
+    #   Pubid::Utils::StringNormalizer.normalize_dashes(str)
+    #   Pubid::Utils::StringNormalizer.normalize_whitespace(str)
+    #   Pubid::Utils::StringNormalizer.split_compound_number(str)
+    #
+    class StringNormalizer
+      # Unicode dash characters that should be normalized to ASCII hyphen
+      DASH_CHARS = ["-", "‑", "‐", "–", "—"].freeze
+
+      # Whitespace characters to normalize to single space
+      WHITESPACE_CHARS = [" ", "\t", "\n", "\r", "\u00A0"].freeze
+
+      class << self
+        # Normalize all dash characters to ASCII hyphen
+        #
+        # @param str [String, nil] input string
+        # @return [String] normalized string with ASCII hyphens
+        #
+        # @example Normalize unicode dashes
+        #   StringNormalizer.normalize_dashes("ISO‑9001") # => "ISO-9001"
+        #   StringNormalizer.normalize_dashes("ISO–9001") # => "ISO-9001"
+        #
+        def normalize_dashes(str)
+          return str if str.nil?
+
+          str.tr(DASH_CHARS.join, "-")
+        end
+
+        # Normalize whitespace to single space and strip
+        #
+        # @param str [String, nil] input string
+        # @return [String] normalized string with single spaces
+        #
+        # @example Normalize whitespace
+        #   StringNormalizer.normalize_whitespace("ISO  9001") # => "ISO 9001"
+        #   StringNormalizer.normalize_whitespace("ISO\t9001") # => "ISO 9001"
+        #
+        def normalize_whitespace(str)
+          return "" if str.nil?
+
+          str.gsub(/[#{WHITESPACE_CHARS.join}]+/, " ").strip
+        end
+
+        # Clean and uppercase abbreviation
+        #
+        # @param str [String, nil] input string
+        # @return [String] cleaned and uppercased abbreviation
+        #
+        # @example Clean abbreviation
+        #   StringNormalizer.clean_abbr("  amd  ") # => "AMD"
+        #   StringNormalizer.clean_abbr("Amd") # => "AMD"
+        #
+        def clean_abbr(str)
+          return "" if str.nil?
+
+          normalize_whitespace(str).upcase
+        end
+
+        # Split compound number (e.g., "800-53-1" -> ["800", "53", "1"])
+        #
+        # @param str [String] input string
+        # @param separators [Array<String>] separators to split on
+        # @return [Array<String>] split parts
+        #
+        # @example Split compound numbers
+        #   StringNormalizer.split_compound_number("800-53-1")
+        #   # => ["800", "53", "1"]
+        #   StringNormalizer.split_compound_number("800/53")
+        #   # => ["800", "53"]
+        #
+        def split_compound_number(str, separators: ["-", "/"])
+          return [] unless str
+
+          normalized = normalize_dashes(str)
+          normalized.split(/[#{separators.join}]/).reject(&:empty?)
+        end
+
+        # Extract numeric suffix from string
+        #
+        # @param str [String] input string
+        # @return [Array<String, nil>] [number, suffix] or [nil, nil]
+        #
+        # @example Extract number and suffix
+        #   StringNormalizer.extract_number_suffix("800-53r5") # => ["53", "r5"]
+        #   StringNormalizer.extract_number_suffix("ISO") # => [nil, nil]
+        #
+        def extract_number_suffix(str)
+          return [nil, nil] unless str
+
+          match = str.match(/^(\D+)?(\d+)([a-zA-Z]+)?$/)
+          return [nil, nil] unless match
+
+          number = match[2]
+          suffix = match[3]
+          [number, suffix]
+        end
+
+        # Join parts with proper separator, skipping nils
+        #
+        # @param parts [Array] parts to join
+        # @param separator [String] separator between parts
+        # @return [String] joined string
+        #
+        # @example Join parts
+        #   StringNormalizer.join_parts(["ISO", "9001", nil, "2015"], " ")
+        #   # => "ISO 9001 2015"
+        #   StringNormalizer.join_parts(["ISO", nil, "9001"], "-")
+        #   # => "ISO-9001"
+        #
+        def join_parts(parts, separator: "")
+          parts.compact.join(separator)
+        end
+
+        # Truncate string to max length with ellipsis
+        #
+        # @param str [String] input string
+        # @param max_length [Integer] maximum length
+        # @param ellipsis [String] ellipsis string (default: "...")
+        # @return [String] truncated string
+        #
+        # @example Truncate string
+        #   StringNormalizer.truncate("International Standard", 15)
+        #   # => "International ..."
+        #   StringNormalizer.truncate("ISO", 10)
+        #   # => "ISO"
+        #
+        def truncate(str, max_length:, ellipsis: "...")
+          return str if str.nil? || str.length <= max_length
+
+          str[0...(max_length - ellipsis.length)] + ellipsis
+        end
+
+        # Convert to title case (first letter of each word uppercase)
+        #
+        # @param str [String] input string
+        # @return [String] title cased string
+        #
+        # @example Title case
+        #   StringNormalizer.title_case("international standard")
+        #   # => "International Standard"
+        #   StringNormalizer.title_case("ISO/TR")
+        #   # => "ISO/TR"  # Preserves existing caps
+        #
+        def title_case(str)
+          return "" if str.nil?
+
+          str.split.map do |word|
+            if word.upcase == word # Preserve acronyms
+              word
+            else
+              word.capitalize
+            end
+          end.join(" ")
+        end
+
+        # Check if string is blank (nil, empty, or only whitespace)
+        #
+        # @param str [String] input string
+        # @return [Boolean] true if blank
+        #
+        # @example Check blank
+        #   StringNormalizer.blank?(nil) # => true
+        #   StringNormalizer.blank?("") # => true
+        #   StringNormalizer.blank?("  ") # => true
+        #   StringNormalizer.blank?("ISO") # => false
+        #
+        def blank?(str)
+          str.nil? || str.to_s.strip.empty?
+        end
+
+        # Safe to_s method that handles nil
+        #
+        # @param str [String, nil] input string
+        # @return [String] string or empty string
+        #
+        # @example Safe to_s
+        #   StringNormalizer.to_s(nil) # => ""
+        #   StringNormalizer.to_s("ISO") # => "ISO"
+        #
+        def to_s(str)
+          str.nil? ? "" : str.to_s
+        end
+      end
+    end
+  end
+end

data/lib/pubid/utils.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Utils
+    autoload :StringNormalizer, "pubid/utils/string_normalizer"
+  end
+end

data/lib/pubid/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Pubid
-  VERSION = "1.15.21".freeze
+  VERSION = "2.0.0.alpha.10"
 end

data/lib/pubid/w3c/builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    # Turns the parse tree into a concrete identifier: picks the class from the
+    # leading maturity token and splits the captured remainder into slug + date.
+    class Builder
+      # Maturity token -> concrete identifier class name (resolved lazily so the
+      # Identifiers namespace need not be loaded at class-definition time).
+      TYPE_CLASSES = {
+        "NOTE" => "Note",
+        "DNOTE" => "DraftNote",
+        "WD" => "WorkingDraft",
+        "CR" => "CandidateRecommendation",
+        "CRD" => "CandidateRecommendationDraft",
+        "REC" => "Recommendation",
+        "PR" => "ProposedRecommendation",
+        "PER" => "ProposedEditedRecommendation",
+        "SPSD" => "SupersededRecommendation",
+        "OBSL" => "ObsoleteRecommendation",
+      }.freeze
+
+      # A trailing "-<digits>" group is the date only when the digit run is
+      # exactly 8 (YYYYMMDD), 6 (legacy YYMMDD) or 4 (legacy MMDD) wide. No real
+      # W3C slug ends in such a run, so this never mis-splits a slug that merely
+      # ends in a short digit run (e.g. "url-1", "ATAG10").
+      DATE_RE = /\A(.+)-(\d{8}|\d{6}|\d{4})\z/
+
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        number, date = split_date(data[:rest].to_s)
+        klass_for(data[:type]&.to_s).new(number: number, date: date)
+      end
+
+      private
+
+      def klass_for(type)
+        name = TYPE_CLASSES[type] || "Standard"
+        Identifiers.const_get(name)
+      end
+
+      # @return [Array(String, String|nil)] the slug and the optional date
+      def split_date(rest)
+        if (m = DATE_RE.match(rest))
+          [m[1], m[2]]
+        else
+          [rest, nil]
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifier.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    # Base class for every W3C identifier AND the flavor's parse/create entry
+    # point. Concrete identifiers under Pubid::W3c::Identifiers descend from
+    # this class (one per W3C maturity level), so a parsed W3C id is an
+    # instance of Pubid::W3c::Identifier.
+    #
+    # W3C identifiers are flat: a slug `number`, an optional publication `date`
+    # (kept verbatim as a string — width varies: 8-digit YYYYMMDD, or legacy
+    # 6-digit YYMMDD / 4-digit MMDD), and a document-type carried by the
+    # concrete class (its `type_prefix` returns the printed token, e.g. "WD").
+    class Identifier < ::Pubid::Identifier
+      # Document slug, e.g. "charmod", "css-backgrounds-3", "07-WebData".
+      #
+      # This is the relaton index key: Relaton::Index sorts and bsearches every
+      # row on `id.root.number.to_s`, and an empty key degrades that binary
+      # search to a linear scan over the whole index — silently, with no error.
+      # Every W3C identifier is its own root (the flavor has no supplement or
+      # wrapper type), so this attribute is always the key and must never be
+      # empty. It was named `code` before; there is no alias.
+      #
+      # It redefines the parent ::Pubid::Identifier's
+      # `attribute :number, Components::Code` as a plain :string. CLAUDE.md
+      # records that doing so on a class the concrete types INHERIT from can
+      # resolve against the parent definition nondeterministically under
+      # multi-flavor load (the IEEE lesson). That hazard does not apply to W3C's
+      # shape, and the reason is worth keeping: lutaml's `inherited` hook
+      # deep-dups the parent's attribute table into each subclass at
+      # class-definition time (serialize/initialization.rb#initialize_attrs), so
+      # a subclass holds a SNAPSHOT, not a live view. A base-level override is
+      # therefore safe iff every subclass body opens after this body has run —
+      # and Ruby resolves the superclass constant, running this file to
+      # completion, before opening any leaf body. That holds because this class
+      # lives in ONE file, in ONE class body, and is never reopened. Split it
+      # the way IEEE splits its base and a leaf can snapshot a half-built
+      # parent, silently reverting `number` to Components::Code. The `date`
+      # override below has relied on the same property since the flavor landed.
+      # spec/pubid/w3c/root_number_spec.rb pins it, and is only meaningful under
+      # the FULL suite.
+      attribute :number, :string
+      # Publication date verbatim, or nil. Overrides the base Components::Date
+      # attribute with a plain string (same mechanism JIS uses for `number`):
+      # W3C dates are opaque digit runs that must round-trip exactly, and are
+      # never re-parsed as calendar dates.
+      attribute :date, :string
+
+      # Polymorphic type map for lutaml::Model key_value (de)serialization: maps
+      # each subclass's polymorphic_name to its class name so a stored hash
+      # rebuilds the correct identifier type via from_hash.
+      W3C_TYPE_MAP = {
+        "pubid:w3c:standard" => "Pubid::W3c::Identifiers::Standard",
+        "pubid:w3c:note" => "Pubid::W3c::Identifiers::Note",
+        "pubid:w3c:draft-note" => "Pubid::W3c::Identifiers::DraftNote",
+        "pubid:w3c:working-draft" => "Pubid::W3c::Identifiers::WorkingDraft",
+        "pubid:w3c:candidate-recommendation" =>
+          "Pubid::W3c::Identifiers::CandidateRecommendation",
+        "pubid:w3c:candidate-recommendation-draft" =>
+          "Pubid::W3c::Identifiers::CandidateRecommendationDraft",
+        "pubid:w3c:recommendation" =>
+          "Pubid::W3c::Identifiers::Recommendation",
+        "pubid:w3c:proposed-recommendation" =>
+          "Pubid::W3c::Identifiers::ProposedRecommendation",
+        "pubid:w3c:proposed-edited-recommendation" =>
+          "Pubid::W3c::Identifiers::ProposedEditedRecommendation",
+        "pubid:w3c:superseded-recommendation" =>
+          "Pubid::W3c::Identifiers::SupersededRecommendation",
+        "pubid:w3c:obsolete-recommendation" =>
+          "Pubid::W3c::Identifiers::ObsoleteRecommendation",
+      }.freeze
+
+      key_value do
+        map "_type", to: :_type, polymorphic_map: W3C_TYPE_MAP
+        map "number", to: :number
+        map "date", to: :date
+      end
+
+      # Publisher is always "W3C". A plain constant (not a `publisher` method)
+      # so it doesn't shadow the inherited lutaml `publisher` attribute, which
+      # would otherwise fail serialization type validation.
+      PUBLISHER = "W3C"
+
+      # The printed document-type token (e.g. "WD"). nil for the bare-slug
+      # Standard form; concrete typed subclasses override it.
+      def type_prefix
+        nil
+      end
+
+      attr_reader :with_publisher
+
+      # Publication year derived from an 8-digit YYYYMMDD date, else nil. `date`
+      # is a plain string here (not a Components::Date), so the inherited
+      # `year` — which calls `date&.year` — would break; override it.
+      def year
+        return nil unless date.is_a?(::String) && date.length == 8
+
+        date[0, 4]
+      end
+
+      def to_s(with_publisher: true, **opts)
+        @with_publisher = with_publisher
+        render(format: :human, **opts)
+      end
+
+      # from_hash is the shared polymorphic dispatch on Pubid::Identifier;
+      # W3C_TYPE_MAP remains as the key_value polymorphic_map.
+
+      # Parse a W3C identifier string into an identifier object
+      # @param identifier [String] The W3C identifier string to parse
+      # @return [Identifier] The appropriate identifier object
+      # @raise [Pubid::Errors::ParseError] If parsing fails
+      def self.parse(identifier)
+        # Reject pathological inputs before they reach the parser
+        # (CodeQL rb/polynomial-redos barrier — inline .length by design).
+        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)
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/candidate_recommendation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # W3C Candidate Recommendation. Printed token: "CR".
+      # Example: "W3C CR-exi-20091208".
+      class CandidateRecommendation < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :cr,
+            stage_code: :candidate_recommendation,
+            type_code: :cr,
+            abbr: ["CR"],
+            name: "Candidate Recommendation",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :cr, web: :candidate_recommendation,
+            title: "Candidate Recommendation", short: "CR" }
+        end
+
+        def type_prefix
+          "CR"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/candidate_recommendation_draft.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # W3C Candidate Recommendation Draft. Printed token: "CRD".
+      # Example: "W3C CRD-accelerometer-20250212".
+      class CandidateRecommendationDraft < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :crd,
+            stage_code: :candidate_recommendation_draft,
+            type_code: :crd,
+            abbr: ["CRD"],
+            name: "Candidate Recommendation Draft",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :crd, web: :candidate_recommendation_draft,
+            title: "Candidate Recommendation Draft", short: "CRD" }
+        end
+
+        def type_prefix
+          "CRD"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/draft_note.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # Draft W3C Note. Printed token: "DNOTE".
+      # Example: "W3C DNOTE-webcodecs-flac-codec-registration-20240419".
+      class DraftNote < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :dnote,
+            stage_code: :draft_note,
+            type_code: :dnote,
+            abbr: ["DNOTE"],
+            name: "Draft W3C Note",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :dnote, web: :draft_note, title: "Draft W3C Note",
+            short: "DNOTE" }
+        end
+
+        def type_prefix
+          "DNOTE"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/note.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # W3C Note (formerly Working Group / Interest Group Note).
+      # Printed token: "NOTE". Example: "W3C NOTE-xml-names".
+      class Note < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :note,
+            stage_code: :note,
+            type_code: :note,
+            abbr: ["NOTE"],
+            name: "W3C Note",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :note, web: :note, title: "W3C Note", short: "NOTE" }
+        end
+
+        def type_prefix
+          "NOTE"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/obsolete_recommendation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # Obsolete W3C Recommendation. Printed token: "OBSL".
+      # Example: "W3C OBSL-widgets-apis-20181011".
+      class ObsoleteRecommendation < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :obsl,
+            stage_code: :obsolete_recommendation,
+            type_code: :obsl,
+            abbr: ["OBSL"],
+            name: "Obsolete Recommendation",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :obsl, web: :obsolete_recommendation,
+            title: "Obsolete Recommendation", short: "OBSL" }
+        end
+
+        def type_prefix
+          "OBSL"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/proposed_edited_recommendation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # W3C Proposed Edited Recommendation. Printed token: "PER".
+      # Example: "W3C PER-rif-dtb-20121211".
+      class ProposedEditedRecommendation < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :per,
+            stage_code: :proposed_edited_recommendation,
+            type_code: :per,
+            abbr: ["PER"],
+            name: "Proposed Edited Recommendation",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :per, web: :proposed_edited_recommendation,
+            title: "Proposed Edited Recommendation", short: "PER" }
+        end
+
+        def type_prefix
+          "PER"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/proposed_recommendation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # W3C Proposed Recommendation. Printed token: "PR".
+      # Example: "W3C PR-InkML-20110510".
+      class ProposedRecommendation < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :pr,
+            stage_code: :proposed_recommendation,
+            type_code: :pr,
+            abbr: ["PR"],
+            name: "Proposed Recommendation",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :pr, web: :proposed_recommendation,
+            title: "Proposed Recommendation", short: "PR" }
+        end
+
+        def type_prefix
+          "PR"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/recommendation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # W3C Recommendation (a published standard). Printed token: "REC".
+      # Example: "W3C REC-ATAG10-20000203".
+      class Recommendation < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :rec,
+            stage_code: :recommendation,
+            type_code: :rec,
+            abbr: ["REC"],
+            name: "Recommendation",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :rec, web: :recommendation, title: "Recommendation",
+            short: "REC" }
+        end
+
+        def type_prefix
+          "REC"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/w3c/identifiers/standard.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pubid
+  module W3c
+    module Identifiers
+      # Bare-code W3C reference with no maturity token, e.g. "W3C 2dcontext",
+      # "W3C 07-WebData". The default type; carries no `type_prefix`.
+      class Standard < Identifier
+      end
+    end
+  end
+end