pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/components/supplement.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Components
+    # Supplement component — a structured value-object representing the
+    # supplement-specific data (number, date, stage, iteration, type) of a
+    # supplement identifier.
+    #
+    # Union shape across flavors:
+    # - type:    "amd" (amendment), "cor" (corrigendum), "err" (errata),
+    #            "sup" (supplement), or a flavor-specific marker.
+    # - number:  bare sequence number (string preserves leading zeros, "1A"
+    #            combos, etc.).
+    # - date:    publication date of the supplement (Components::Date).
+    # - range_end_date: end of a date range; presence of this marks the
+    #            supplement as a range. (NIST/NBS uses supJan1924-Jun1925.)
+    # - stage:   the stage the supplement is in (e.g., WD Amd, CD Amd).
+    # - iteration: stage iteration (e.g., the ".2" in "WD.2 Amd").
+    # - has_revision: "suprev" marker — supplement that itself carries a
+    #            revision. (NIST-specific.)
+    # - suffix:  escape hatch for patterns not yet modeled.
+    #
+    # Format-aware via render(context:). The human form stacks fields in the
+    # order they appear in the printed supplement; the URN form joins number
+    # and year with ":".
+    class Supplement < Lutaml::Model::Serializable
+      DEFAULT_TYPE = "sup"
+
+      attribute :type, :string, default: -> { DEFAULT_TYPE }
+      attribute :number, :string
+      attribute :date, Date
+      attribute :range_end_date, Date
+      attribute :stage, Stage
+      attribute :iteration, Components::Iteration
+      attribute :has_revision, :boolean, default: false
+      attribute :suffix, :string
+
+      IDENTITY_FIELDS = %i[
+        type number date range_end_date stage iteration has_revision suffix
+      ].freeze
+
+      # Fields whose presence indicates the supplement carries data.
+      # `type` is excluded — it always has a value (the default "sup") but
+      # doesn't mean the supplement carries content.
+      CONTENT_FIELDS = %i[
+        number date range_end_date stage iteration has_revision suffix
+      ].freeze
+
+      # True when the supplement carries any data. Distinguishes a present-
+      # but-empty supplement (bare marker, "sup") from no supplement at all.
+      def present?
+        CONTENT_FIELDS.any? { |f| present_value?(public_send(f)) }
+      end
+
+      # True when this supplement spans a date range (start + end set).
+      def range?
+        date&.present? && range_end_date&.present?
+      end
+
+      def render(context: nil)
+        return render_urn if context&.format == :urn
+
+        render_human
+      end
+
+      def to_s(**opts)
+        render(context: opts[:context])
+      end
+
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        identity_fields.all? { |f| public_send(f) == other.public_send(f) }
+      end
+
+      alias eql? ==
+
+      def hash
+        @hash ||= [self.class, *identity_fields.map { |f| public_send(f) }].hash
+      end
+
+      private
+
+      def identity_fields
+        IDENTITY_FIELDS
+      end
+
+      def non_empty?(value)
+        return false if value.nil?
+
+        value.is_a?(String) ? !value.empty? : value.present?
+      end
+
+      def present_value?(value)
+        return value if [true, false].include?(value)
+        return false if value.nil?
+
+        value.is_a?(String) ? !value.empty? : value.present?
+      end
+
+      def number?
+        non_empty?(number)
+      end
+
+      def suffix?
+        non_empty?(suffix)
+      end
+
+      def stage_abbr
+        return nil if stage.nil? || stage.abbr.nil?
+
+        abbr = stage.abbr.to_s
+        abbr.empty? ? nil : abbr
+      end
+
+      # Human / mr: stack fields in canonical order.
+      #   "1924"            (year)
+      #   "Jan1924"         (month + year)
+      #   "3/1926"          (number + year)
+      #   "1"               (number)
+      #   "A"               (suffix)
+      #   "Jan1924-Jun1925" (range)
+      def render_human
+        return early_marker if has_revision || suffix?
+        return date_range_string if range?
+
+        assemble_body
+      end
+
+      def early_marker
+        has_revision ? "rev" : suffix.to_s
+      end
+
+      def assemble_body
+        body = number_or_date_string
+        body += iteration_suffix if include_iteration?
+        stage_abbr ? "#{stage_abbr}#{body}" : body
+      end
+
+      def include_iteration?
+        iteration && stage_abbr.nil?
+      end
+
+      def render_urn
+        return "" unless present?
+
+        [number&.to_s, date&.year&.to_s].compact.reject(&:empty?).join(":")
+      end
+
+      def iteration_suffix
+        "-#{iteration.number}"
+      end
+
+      def date_range_string
+        "#{date_string(date)}-#{date_string(range_end_date)}"
+      end
+
+      def number_or_date_string
+        return date_string(date) unless number?
+
+        date&.present? ? "#{number}/#{date_string(date)}" : number.to_s
+      end
+
+      # Render the body of a date fragment preserving the original month
+      # abbreviation when month is a non-numeric string. Falls back to
+      # Components::Date#render when month is numeric.
+      def date_string(date_value)
+        return "" unless date_value&.present?
+
+        if month_abbreviation?(date_value)
+          "#{date_value.month}#{date_value.year}"
+        else
+          date_value.render(context: nil)
+        end
+      end
+
+      def month_abbreviation?(date_value)
+        date_value.month && !date_value.month.match?(/^\d+$/)
+      end
+    end
+  end
+end

data/lib/pubid/components/type.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Components
+    # Resource type component (a set of defined resource types)
+    #
+    # Human render: abbreviation with flavor-specific separator.
+    # URN render: type code (e.g. "tr", "ts") per RFC 5141-bis.
+    class Type < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :abbr, :string
+      attribute :type_code, :string
+
+      def to_s(context: nil, has_prefix: false)
+        return "" unless abbr
+
+        if context && !context.should_render_type?(abbr)
+          return ""
+        end
+
+        if context
+          sep = context.type_separator_for(has_prefix)
+          sep == "" ? abbr : "#{sep}#{abbr}"
+        else
+          has_prefix ? " #{abbr}" : "/#{abbr}"
+        end
+      end
+
+      def render(context: nil)
+        return type_code.to_s if context&.urn? && type_code
+
+        name.to_s
+      end
+
+      def hash
+        @hash ||= [type_code, abbr].compact.map(&:hash).hash
+      end
+
+      def eql?(other)
+        return false unless other.is_a?(self.class)
+
+        type_code == other.type_code && abbr == other.abbr
+      end
+    end
+  end
+end

data/lib/pubid/components/typed_stage.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Components
+    # TypedStage component (combined stage + type, e.g. "DTR", "FDIS")
+    #
+    # Human render: typed-stage abbreviation with flavor-specific separator.
+    # URN render: stage code (RFC 5141-bis: stage-XX.XX format handled by urn_generator).
+    class TypedStage < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :code, :string
+      attribute :type_code, :string
+      attribute :stage_code, :string
+      attribute :abbr, :string, collection: true
+      attribute :harmonized_stages, :string, collection: true
+      attribute :original_abbr, :string
+      attribute :short_abbr, :string
+      attribute :long_abbr, :string
+
+      def to_stage
+        Stage.new(
+          name: name,
+          stage_code: stage_code,
+          abbr: abbr.first,
+          harmonized_stages: harmonized_stages,
+        )
+      end
+
+      def to_type
+        Type.new(
+          name: name,
+          type_code: type_code,
+          abbr: abbr.first,
+        )
+      end
+
+      def render(context: nil)
+        return code.to_s if context&.urn? && code
+
+        abbreviation(format_long: context&.stage_format_long || false)
+      end
+
+      def abbreviation(format_long: true)
+        if format_long && long_abbr
+          long_abbr
+        elsif !format_long && short_abbr
+          short_abbr
+        else
+          abbr.first
+        end
+      end
+
+      def canonical_abbreviation
+        abbr.first
+      end
+    end
+  end
+end

data/lib/pubid/components.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Components
+    autoload :Adoption, "pubid/components/adoption"
+    autoload :Code, "pubid/components/code"
+    autoload :Date, "pubid/components/date"
+    autoload :Edition, "pubid/components/edition"
+    autoload :Iteration, "pubid/components/iteration"
+    autoload :Language, "pubid/components/language"
+    autoload :Locality, "pubid/components/locality"
+    autoload :Publisher, "pubid/components/publisher"
+    autoload :Relationship, "pubid/components/relationship"
+    autoload :Stage, "pubid/components/stage"
+    autoload :Supplement, "pubid/components/supplement"
+    autoload :Type, "pubid/components/type"
+    autoload :TypedStage, "pubid/components/typed_stage"
+  end
+end

data/lib/pubid/core/pattern_doc_generator.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+# Pattern documentation generator for PubID flavors.
+# Reads identifier types, typed stages, and fixtures to produce markdown docs.
+module Pubid
+  module Core
+    class PatternDocGenerator
+      attr_reader :flavor
+
+      FLAVOR_NAMES = {
+        "iso" => "ISO (International Organization for Standardization)",
+        "iec" => "IEC (International Electrotechnical Commission)",
+        "ieee" => "IEEE (Institute of Electrical and Electronics Engineers)",
+        "nist" => "NIST (National Institute of Standards and Technology)",
+        "cen" => "CEN (European Committee for Standardization)",
+        "bsi" => "BSI (British Standards Institution)",
+        "ccsds" => "CCSDS (Consultative Committee for Space Data Systems)",
+        "itu" => "ITU (International Telecommunication Union)",
+        "etsi" => "ETSI (European Telecommunications Standards Institute)",
+        "jis" => "JIS (Japanese Industrial Standards)",
+        "plateau" => "PLATEAU (Japanese urban planning standards)",
+        "asme" => "ASME (American Society of Mechanical Engineers)",
+        "astm" => "ASTM (ASTM International)",
+        "ashrae" => "ASHRAE (American Society of Heating, Refrigerating and Air-Conditioning Engineers)",
+        "api" => "API (American Petroleum Institute)",
+        "cie" => "CIE (International Commission on Illumination)",
+        "csa" => "CSA (Canadian Standards Association)",
+        "idf" => "IDF (International Dairy Federation)",
+        "oiml" => "OIML (International Organization of Legal Metrology)",
+        "jcgm" => "JCGM (Joint Committee for Guides in Metrology)",
+        "sae" => "SAE (SAE International)",
+        "amca" => "AMCA (Air Movement and Control Association)",
+        "ansi" => "ANSI (American National Standards Institute)",
+      }.freeze
+
+      def initialize(flavor)
+        @flavor = flavor
+      end
+
+      def generate
+        lines = []
+        lines << "# #{flavor_upcase} Identifier Patterns"
+        lines << ""
+        lines << flavor_description
+        lines << ""
+        lines << "## Entry Point"
+        lines << ""
+        lines << "```ruby"
+        lines << "require 'pubid/#{flavor}'"
+        lines << "id = Pubid::#{flavor.capitalize}.parse(\"...\")"
+        lines << "```"
+        lines << ""
+
+        identifier_types = collect_identifier_types
+        if identifier_types.any?
+          lines << "## Identifier Types"
+          lines << ""
+
+          identifier_types.each do |type_name, type_info|
+            lines << "### #{type_name}"
+            lines << ""
+            lines << "**Class:** `#{type_info[:class_path]}`"
+            lines << ""
+
+            if type_info[:typed_stages].any?
+              lines << "#### Typed Stages"
+              lines << ""
+              lines << stage_table(type_info[:typed_stages])
+              lines << ""
+            end
+          end
+        end
+
+        fixtures = collect_fixtures
+        if fixtures.any?
+          lines << "## Examples"
+          lines << ""
+          lines << fixture_table(fixtures)
+          lines << ""
+        end
+
+        urn_gen = has_urn_generator?
+        lines << "## URN Support"
+        lines << ""
+        lines << urn_gen ? "Yes - `id.to_urn` generates URN output." : "No URN generator defined."
+        lines << ""
+
+        update_codes = has_update_codes?
+        lines << "## Pre-parse Normalization"
+        lines << ""
+        lines << if update_codes
+                   "See `data/#{flavor}/update_codes.yaml` for legacy format mappings."
+                 else
+                   "No normalization rules defined."
+                 end
+        lines << ""
+
+        lines.join("\n")
+      end
+
+      def collect_identifier_types
+        types = {}
+        idents_dir = File.join(__dir__, "..", "..", "pubid", flavor,
+                               "identifiers")
+
+        return types unless Dir.exist?(idents_dir)
+
+        Dir.glob(File.join(idents_dir, "*.rb")).each do |f|
+          type_name = File.basename(f, ".rb").gsub("_",
+                                                   " ").split.map(&:capitalize).join(" ")
+          class_path = "Pubid::#{flavor.capitalize}::Identifiers::#{type_name.gsub(
+            ' ', ''
+          )}"
+
+          typed_stages = extract_typed_stages(f)
+
+          types[type_name] = {
+            class_path: class_path,
+            typed_stages: typed_stages,
+          }
+        end
+
+        types
+      rescue StandardError
+        types
+      end
+
+      def has_urn_generator?
+        File.exist?(File.join(__dir__, "..", "..", "pubid", flavor,
+                              "urn_generator.rb"))
+      end
+
+      def has_update_codes?
+        File.exist?(File.join(__dir__, "..", "..", "..", "data", flavor,
+                              "update_codes.yaml"))
+      end
+
+      private
+
+      def flavor_upcase
+        flavor.upcase
+      end
+
+      def flavor_description
+        FLAVOR_NAMES[flavor] || "#{flavor.upcase} identifiers"
+      end
+
+      def extract_typed_stages(file_path)
+        content = File.read(file_path)
+        stages = []
+
+        # Find the TYPED_STAGES constant block
+        return stages unless /TYPED_STAGES\s*=\s*\[/.match?(content)
+
+        # Extract everything from TYPED_STAGES = [ to the matching ].freeze or end of array
+        # Use a simpler approach: scan between TYPED_STAGES = [ and ].freeze
+        start_idx = content.index(/TYPED_STAGES\s*=\s*\[/)
+        return stages unless start_idx
+
+        # Find the matching closing bracket
+        bracket_count = 0
+        end_idx = nil
+        content[start_idx..].each_char.with_index do |char, i|
+          case char
+          when "["
+            bracket_count += 1
+          when "]"
+            bracket_count -= 1
+            if bracket_count.zero?
+              end_idx = start_idx + i
+              break
+            end
+          end
+        end
+
+        return stages unless end_idx
+
+        stage_block = content[start_idx..end_idx]
+
+        # Match TypedStage.new( ... ) including multiline
+        stage_block.scan(/(?:Pubid::Components::)?TypedStage\.new\((.*?)\)/m).each do |match|
+          stage_text = match.first
+          name = extract_kw_arg(stage_text, "name")
+          abbr = extract_kw_arg(stage_text, "abbr")
+          stage_code = extract_kw_arg(stage_text, "stage_code")
+          harmonized = extract_kw_arg(stage_text, "harmonized_stages")
+
+          if name || abbr
+            stages << {
+              name: name,
+              abbr: abbr,
+              stage_code: stage_code,
+              harmonized_stages: harmonized,
+            }
+          end
+        end
+
+        stages
+      end
+
+      def extract_kw_arg(text, key)
+        case text
+        when /#{key}:\s*"([^"]*)"/
+          $1
+        when /#{key}:\s*:(\w+)/
+          ":#{$1}"
+        when /#{key}:\s*\[([^\]]*)\]/
+          $1
+        end
+      end
+
+      def collect_fixtures
+        fixtures = []
+        pass_dir = File.join(__dir__, "..", "..", "..", "spec", "fixtures",
+                             flavor, "pass")
+
+        return fixtures unless Dir.exist?(pass_dir)
+
+        Dir.glob(File.join(pass_dir, "*.txt")).each do |f|
+          lines = File.readlines(f, chomp: true).reject(&:empty?).first(5)
+          fixtures.concat(lines)
+        end
+
+        fixtures.uniq.first(20)
+      rescue StandardError
+        fixtures
+      end
+
+      def fixture_table(fixtures)
+        lines = []
+        lines << "| # | Example |"
+        lines << "|---|---------|"
+        fixtures.each_with_index do |f, i|
+          lines << "| #{i + 1} | `#{f}` |"
+        end
+        lines.join("\n")
+      end
+
+      def stage_table(stages)
+        lines = []
+        lines << "| Abbr | Name | Stage Code | Harmonized Codes |"
+        lines << "|------|------|-----------|-----------------|"
+        stages.each do |s|
+          lines << "| #{s[:abbr]} | #{s[:name]} | #{s[:stage_code]} | #{s[:harmonized_stages]} |"
+        end
+        lines.join("\n")
+      end
+
+      # Cross-flavor comparison table
+      def self.generate_cross_flavor_table(flavors)
+        lines = []
+        lines << "# PubID Identifier Pattern Cross-Flavor Comparison"
+        lines << ""
+        lines << "| Flavor | ID Types | Typed Stages | URN Support | Normalization |"
+        lines << "|--------|----------|-------------|-------------|--------------|"
+
+        flavors.sort.each do |f|
+          gen = new(f)
+          types = gen.collect_identifier_types.keys.length
+          stages = gen.collect_identifier_types.values.sum do |t|
+            t[:typed_stages].length
+          end
+          urn = gen.has_urn_generator? ? "Yes" : "No"
+          norm = gen.has_update_codes? ? "Yes" : "No"
+          lines << "| #{f.upcase} | #{types} | #{stages} | #{urn} | #{norm} |"
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/pubid/core/update_codes.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Pubid
+  module Core
+    # Centralized update_codes loader and applier.
+    #
+    # Reads YAML files from data/{flavor}/update_codes.yaml and applies
+    # substitution patterns to normalize malformed identifiers BEFORE parsing.
+    #
+    # Each flavor's parse entry point calls UpdateCodes.apply(code, :flavor)
+    # before any parser-specific preprocessing.
+    #
+    # Format in YAML files:
+    #   plain string match: "IEC 60285-/1:1989"  →  "IEC 60285-1:1989"
+    #   regex match:        "/^NBS CIRC sup$/"   →  "NBS CIRC 24e7sup"
+    #   regex with flags:   "/^nbs\\b/i"          →  "NBS"
+    #
+    # Plain strings use full-line anchoring (^pattern$).
+    # Regex patterns are wrapped in /.../ slashes with optional trailing flags
+    # (i = IGNORECASE, m = MULTILINE, x = EXTENDED) and applied via gsub.
+    class UpdateCodes
+      DATA_DIR = Pathname.new(__dir__).join("../../../data").expand_path
+
+      # Regex literal: /body/flags  where flags is optional (i, m, x).
+      REGEX_LITERAL = %r{\A/(.*)/([imx]*)\z}m
+
+      class << self
+        # Apply update_codes substitutions for the given flavor.
+        #
+        # @param code [String] identifier string to normalize
+        # @param flavor [Symbol, String] flavor name
+        #   (e.g., :iso, :iec, :ieee, :nist)
+        # @return [String] normalized identifier string
+        #
+        # @example
+        #   UpdateCodes.apply("IEC 60285-/1:1989", :iec)
+        #   # => "IEC 60285-1:1989"
+        def apply(code, flavor)
+          codes = for_flavor(flavor)
+          return code if codes.nil? || codes.empty?
+
+          codes.each do |from, to|
+            code = code.gsub(compile_pattern(from), to.to_s)
+          end
+          code
+        end
+
+        # Get the loaded update_codes hash for a flavor (cached).
+        #
+        # @param flavor [Symbol, String] flavor name
+        # @return [Hash, nil] the YAML hash, or nil if file doesn't exist
+        def for_flavor(flavor)
+          @cache ||= {}
+          flavor_key = flavor.to_s.to_sym
+          @cache[flavor_key] ||= load_yaml(flavor_key)
+        end
+
+        # Available flavors that have update_codes files.
+        #
+        # @return [Array<Symbol>] flavors with data/{flavor}/update_codes.yaml
+        def flavors
+          @flavors ||= DATA_DIR.children.select(&:directory?).map do |dir|
+            dir.basename.to_s.to_sym
+          end.select { |f| (DATA_DIR / f.to_s / "update_codes.yaml").exist? }
+        end
+
+        # Compile a YAML key into a Regexp. Plain strings are anchored to the
+        # full line; regex literals support optional trailing flags.
+        def compile_pattern(from)
+          match = from.to_s.match(REGEX_LITERAL)
+          return /^#{Regexp.escape(from.to_s)}$/ unless match
+
+          Regexp.new(match[1], compile_options(match[2]))
+        end
+
+        def compile_options(flags)
+          options = 0
+          options |= Regexp::IGNORECASE if flags.include?("i")
+          options |= Regexp::MULTILINE if flags.include?("m")
+          options |= Regexp::EXTENDED if flags.include?("x")
+          options
+        end
+
+        private
+
+        def load_yaml(flavor)
+          yaml_path = DATA_DIR / flavor.to_s / "update_codes.yaml"
+          return nil unless yaml_path.exist?
+
+          YAML.load_file(yaml_path)
+        end
+      end
+    end
+  end
+end

data/lib/pubid/core.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pubid
+  # Core module for shared functionality across all flavors.
+  module Core
+    autoload :UpdateCodes, "#{__dir__}/core/update_codes"
+  end
+end